qiskit-experiments
qiskit-experiments copied to clipboard
CI for linting docs
Summary
Added linting of Sphinx docs to the lint CI job with the tox environment docs-lint
. The job will fail on broken references and links.
Details and comments
- A new
docs/lint/conf.py
is added for this linting setting. It currently has a manual list of regex objects to ignore, because there are a lot of deprecated objects in the release notes that need to be manually updated or added to the ignore list. - The arxiv autolink in docstrings has been changed to the abstract instead of the PDF for user friendliness.
- The docs are no longer incompatible with the newest sphinx-autodoc-typehints so the version pin from #1017 has been removed. This closes #1018.
- Actual format linting like sphinx-lint is not yet included.
I'm having a hard time with the new tox -edocs-lint
CI job. It runs all the way through on Mac (besides the known issue of many warnings). On Linux it's currently crashing early with
sphinx.errors.ExtensionError: Handler <function _get_versions at 0x7f4a4013c0d0> for event 'config-inited' threw an exception (exception: Command '['git', 'describe', '--abbrev=0']' returned non-zero exit status 128.)
and I'm not sure yet why that's happening just in this mode.