Formatting within the using_commands documentation does not appear correct
Overview
Here is the documentation for using BuildStream commands: https://buildstream.gitlab.io/buildstream/using_commands.html
This page is created using the sphinx-click plugin which automatically generates documentation. However, command option lists are not displaying on the webpage in the way one would expect.
Important remark
Note that fixing (most of) this will require an upstream patch.
- An issue has already been filed for this: https://github.com/click-contrib/sphinx-click/issues/8
Problems
-
Command options that take option arguments are not sensibly named, e.g. The
bst build --track
option shows:Because of the way it is defined here: https://gitlab.com/BuildStream/buildstream/blob/master/buildstream/_frontend/cli.py#L173
@click.option('--track', 'track_', multiple=True, type=click.Path(dir_okay=False, readable=True), help="Specify elements to track during the build. Can be used " "repeatedly to specify multiple elements")
Preferably, this should show:
--track <element>
And there are many instances of this throughout the using_commands documentation.
-
Lists within
@click.pass_obj()
are not being converted properly when using the \b flag.One example is for the
bst fetch
command: https://gitlab.com/BuildStream/buildstream/blob/master/buildstream/_frontend/cli.py#L242def fetch(app, elements, deps, track_, except_): """Fetch sources required to build the pipeline By default this will only try to fetch sources which are required for the build plan of the specified target element, omitting sources for any elements which are already built and available in the artifact cache. Specify `--deps` to control which sources to fetch: \b none: No dependencies, just the element itself plan: Only dependencies required for the build plan all: All dependencies """
Which generates the following documentation:
Notice how the list has not been generated correctly.
-
Titles are not being generated correctly
One example is for the
bst show
command documentation: https://gitlab.com/BuildStream/buildstream/blob/master/buildstream/_frontend/cli.py#L411Which has rendered like so: