Update Commands section in wiki documentation

[osma]

The Commands page in the wiki is getting really out of date and it is missing commands such as annif index. I think it needs an overhaul. It would be best to try to generate some of the content automatically from the CLI command help.

Thanks to @cbartz for pointing this out.

[juhoinkinen]

These tools seem like they could be used for the task (maybe they were just mentioned by @cbartz):

• md-click
• mkdocs-click

[juhoinkinen]

I checked how md-click would work.

The current release requires Click version <=7.1.2, and as such does not work with Annif. There is an open PR from a fork, which upgrades the requirement. Using that fork I got this kind of output for each command (each in separate .md file):

list-projects

List available projects.

Usage

Usage: list-projects [OPTIONS]

Options

• verbosity:

  • Type: STRING
  • Default: error
  • Usage: --verbosity -v

  Either CRITICAL, ERROR, WARNING, INFO or DEBUG

• projects:

  • Type: <click.types.Path object at 0x7f3326082310>
  • Default: none
  • Usage: -p --projects

  Set path to project configuration file or directory

• help:

  • Type: BOOL
  • Default: false

CLI Help

Usage: list-projects [OPTIONS]

  List available projects.

Options:
  -v, --verbosity LVL  Either CRITICAL, ERROR, WARNING, INFO or DEBUG
  -p, --projects PATH  Set path to project configuration file or directory
  -v, --verbosity LVL  Either CRITICAL, ERROR, WARNING, INFO or DEBUG
  --help               Show this message and exit.

[juhoinkinen]

I hoped mkdocs-click would allow using a custom template for the whole wiki page, but this tool renders the Click commands documentation only to html. Markdown is used only in the template for building the html page. So mkdocs-click is not applicable for this task.

Then I tried sphinx-click plugin for Sphinx with sphinx-markdown-builder. It can use a Sphinx template in .rst format. Output can look like following:

Supported CLI commands in Annif

These are the command line commands of Annif, with REST API equivalents when applicable. Most of these methods take a projectid parameter. Projects are identified by alphanumeric strings (A-Za-z0-9_-).

annif list-projects

List available projects.

annif list-projects [OPTIONS]

Options

-v(, --verbosity( <LVL>)

Either CRITICAL, ERROR, WARNING, INFO or DEBUG

-p(, --projects( )

Set path to project configuration file or directory

-v(, --verbosity( <LVL>)

Either CRITICAL, ERROR, WARNING, INFO or DEBUG

REST equivalent::

GET /projects/

annif show-project

Show information about a project.

annif show-project [OPTIONS] PROJECT_ID

Options

-v(, --verbosity( <LVL>)

Either CRITICAL, ERROR, WARNING, INFO or DEBUG

-p(, --projects( )

Set path to project configuration file or directory

Arguments

PROJECT_ID()

Required argument

REST equivalent::

GET /projects/<projectid>

The .rst template for above:

===============================
Supported CLI commands in Annif
===============================

These are the command line commands of Annif, with REST API equivalents when applicable.
Most of these methods take a projectid parameter. Projects are identified by alphanumeric strings `(A-Za-z0-9_-)`.

.. click:: annif.cli:run_list_projects
   :prog: annif list-projects

REST equivalent:::

  GET /projects/

.. click:: annif.cli:run_show_project
   :prog: annif show-project

REST equivalent:::

   GET /projects/<projectid>

Unfortunately there are the extra parenthesis following each option and argument, which appear on markdown generation. In normal Sphinx build to html the extra parenthesis are not present.

[juhoinkinen]

Unfortunately there are the extra parenthesis following each option and argument, which appear on markdown generation. In normal Sphinx build to html the extra parenthesis are not present.

sphinx-markdown-builder has a maintained fork sphinx-notes/markdown-builder and using it the extra parenthesis are not inserted to the the markdown file; I continue with that.