Autogenerated CLI commands documentation on ReadTheDocs

[juhoinkinen]

Switches to document Annif CLI commands on annif.readthedocs.io with automated builds instead of manually maintaining documentation in a GitHub wiki page

Template for the page is in docs/source/commands.rst.

Due to an issue with sphinx-rtd-theme (not showing bullet points in TOC lists) an older version of docutils (0.16) is used.

Edit: Also upgrades to Click 8.1.* to allow sphinx-click to access full docstring after truncation marker \f

Closes #595.

[codecov[bot]]

Codecov Report

Merging #611 (3da99fa) into master (c291930) will increase coverage by 0.00%. The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #611   +/-   ##
=======================================
  Coverage   99.58%   99.58%           
=======================================
  Files          87       87           
  Lines        5840     5850   +10     
=======================================
+ Hits         5816     5826   +10     
  Misses         24       24           

Impacted Files	Coverage Δ
annif/cli.py	99.63% <ø> (ø)
tests/test_cli.py	100.00% <0.00%> (ø)
tests/test_rest.py	100.00% <0.00%> (ø)
tests/test_project.py	100.00% <0.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[sonarcloud[bot]]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.0% Duplication

[juhoinkinen]

The document generation is semi-automatic, so after adding new CLI commands (e.g. #614), references to them need to be added to the docs/source/commands.rst template.

[juhoinkinen]

Documentation build from this branch is displayed on https://annif.readthedocs.io/en/autogenerate-commands-wiki/index.html.

To build documentation locally run make clean; make html in docs/ with venv activated.

[juhoinkinen]

I enabled an automation rule on ReadTheDocs that should, for each new release, create a new version of the docs with the semver name and show it in the list of docs versions.

The "latest" docs version tracks the master branch and the "stable" version tracks the latest release.

[osma]

Great work! Now the next step is replacing the content of the Commands page in the wiki with a link to RTD, right?

[juhoinkinen]

Great work! Now the next step is replacing the content of the Commands page in the wiki with a link to RTD, right?

Yes, but I think it is best to do that after next release, because then the link can be to the CLI page of the "stable" docs version; at the moment that CLI page exists only on the "latest" version of docs.

[osma]

Fine, as long as we won't forget doing that during the release :)