qiskit-experiments icon indicating copy to clipboard operation
qiskit-experiments copied to clipboard

CI for linting docs

Open coruscating opened this issue 1 year ago • 2 comments

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.

coruscating avatar Mar 14 '23 23:03 coruscating

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.

coruscating avatar Mar 17 '23 02:03 coruscating

CLA assistant check
All committers have signed the CLA.

CLAassistant avatar Jul 18 '23 13:07 CLAassistant