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

1. 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.

2. 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#L242

   def 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.

3. 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#L411

   Which has rendered like so: