Autogenerate sctool docs from yaml files by dgarcia360 · Pull Request #2987 · scylladb/scylla-manager

dgarcia360 · 2021-12-22T10:30:47Z

Autogenerates sctool docs from YAML files using the extension sphinxcontrib.datatemplates.

How to test this PR

Clone this PR. For more information, see Cloning pull requests locally.
Enter the docs folder, and run:

make preview

Open http://127.0.0.1:5500/sctool/ with your favorite browser and preview the docs.

Before merging this PR ...

Would it be possible to update the autogenerated YAML files?

Sphinx needs a special character to detect lists. For example:

    '*' - matches any number of any characters including none
    '?' - matches any single character
    '[abc]' - matches one character given in the bracket
    '[a-z]' - matches one character from the range given in the bracket

Must be:

    * '*' - matches any number of any characters including none
    * '?' - matches any single character
    * '[abc]' - matches one character given in the bracket
    * '[a-z]' - matches one character from the range given in the bracket

To highlight inline-code (e.g. abc), replace the single quotes as follows 'abc' -> ``[abc]``.

Future improvements

Add a collapsible component in the theme to hide "inherited options".
Support for more than one example per command. For example, instead of:

example: |
  sctool status -c prod-cluster
  Datacenter: eu-west

The example key could look like this:

examples: 
   - name: Example A 
      description: Example description
     command: sctool xyz
   - name: Example B
      description: Example description
     command: sctool xyz

Adding the new keys name and description will also be possible to format commands as code-blocks and descriptions as regular text.

mmatczuk · 2021-12-22T13:19:23Z

@dgarcia360 please note that there are changes in commands and command layout.
There is no point to find an exact mapping here.

Replace characters test Remove supress_warning Rollback change Update list format Add task commands Added example Rollback Rollback Rollback Hide titles if values not set Rollback

mmatczuk · 2022-01-05T09:57:44Z

@dgarcia360 can we merge it i.e. won't it break the 2.5 2.6 and so on?
We want that for master only for now.

dgarcia360 · 2022-01-10T20:32:50Z

@mmatczuk I've tested it locally and it should not break previous versions.

dgarcia360 · 2022-01-10T20:37:40Z

Notes from 05th Jan 2022 call with @tzach

Once we merge this PR:

@dgarcia360 will update the docstrings as described in Before merging this PR, and submit a PR.
@dgarcia360 will create issues for the recommendations described in Future improvements.