Formatting within the using_commands documentation does not appear correct

[Cynical-Optimist]

See original issue on GitLab
In GitLab by [Gitlab user @jennis] on Mar 27, 2018, 11:20

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: Documentation ignores the \b characters in docstrings click-contrib/sphinx-click#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

   [[Gitlab user @click]](https://gitlab.com/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 [[Gitlab user @click]](https://gitlab.com/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:

   

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Mar 27, 2018, 12:02

Please check if this is not a duplicate of an existing issue.

Note that the upstream issue I filed when discovering this is here

[Cynical-Optimist]

In GitLab by [Gitlab user @jennis] on Mar 27, 2018, 13:55

It does not seem to be a duplicate of any existing issues. However, it is similar to #8. Please let me know if you disagree.

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Mar 28, 2018, 04:25

I should also point out another related issue, the same problem happens in man page generation

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Mar 28, 2018, 04:26

It does not seem to be a duplicate of any existing issues. However, it is similar to #8. Please let me know if you disagree.

This is a different issue from #8, which is mostly regarding streamlining of our own build process.

[Cynical-Optimist]

In GitLab by [Gitlab user @jennis] on Jun 21, 2018, 17:08

changed the description

[Cynical-Optimist]

In GitLab by [Gitlab user @jennis] on Jun 21, 2018, 17:09

changed the description

[Cynical-Optimist]

In GitLab by [Gitlab user @jennis] on Jun 21, 2018, 17:10

changed the description

[Cynical-Optimist]

In GitLab by [Gitlab user @jennis] on Jun 21, 2018, 17:12

changed the description

[Cynical-Optimist]

In GitLab by [Gitlab user @jennis] on Jun 21, 2018, 17:16

changed title from Formatting within the {-invoking-} documentation does not appear correct to Formatting within the {+usign_commands+} documentation does not appear correct

[Cynical-Optimist]

In GitLab by [Gitlab user @danielsilverstone-ct] on Sep 13, 2018, 16:41

changed title from Formatting within the usi{-gn-}_commands documentation does not appear correct to Formatting within the usi{+ng+}_commands documentation does not appear correct

[Cynical-Optimist]

In GitLab by [Gitlab user @knownexus] on Oct 2, 2018, 10:36

I have replied to the isue that [Gitlab user @tristanvb] raised and have made a pull request for my fix

[Cynical-Optimist]

In GitLab by [Gitlab user @LaurenceUrhegyi] on Oct 24, 2018, 16:50

removed milestone

[Cynical-Optimist]

In GitLab by [Gitlab user @cs-shadow] on Feb 21, 2020, 22:25

It is worth noting that (1) and (2) are now fixed.

(1) because we don't have any such options that have different names than the CLI options.

(2) because the upstream issue is now fixed and we now see our lists correctly.

[Cynical-Optimist]

In GitLab by [Gitlab user @cs-shadow] on Feb 21, 2020, 23:31

Reg. (3) - titles are not generated correctly - this is actually a limitation of Sphinx where sections are not allowed within docstrings. See https://sphinx-dev.narkive.com/7rqrxjgL/headings-in-docstrings for some related discussion.

We can make the word FORMAT look more prominent by formatting it like .. rubric:: FORMAT. (This is also what sphinx-click uses for things like Options and Arguments.) This would look fine in the generated html, but would appear literally in the help text, which is not ideal.

The underline for FORMAT at least appears on a new line now so it doesn't look as bad as in the original bug report. But, I don't think there's an easy way to make both the CLI help text and the generated html look good at the moment.

[Cynical-Optimist]

In GitLab by [Gitlab user @cs-shadow] on Feb 22, 2020, 18:23

mentioned in commit e624b2d791ee16e0a0a14c643904c3c0a4bad50c

[Cynical-Optimist]

In GitLab by [Gitlab user @cs-shadow] on Feb 22, 2020, 18:25

mentioned in merge request !1824

[Cynical-Optimist]

In GitLab by [Gitlab user @cs-shadow] on Mar 4, 2020, 15:51

mentioned in commit 8edf482

[Cynical-Optimist]

In GitLab by [Gitlab user @cs-shadow] on Mar 4, 2020, 16:51

closed via merge request !1824

[Cynical-Optimist]

In GitLab by [Gitlab user @cs-shadow] on Mar 4, 2020, 16:51

mentioned in commit 71179f8