Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Formatting within the using_commands documentation does not appear correct #323

Closed
BuildStream-Migration-Bot opened this issue Feb 2, 2021 · 19 comments
Closed

Formatting within the using_commands documentation does not appear correct #323

BuildStream-Migration-Bot opened this issue Feb 2, 2021 · 19 comments
Labels
bug Something isn't working documentation Improvements or additions to documentation

Comments

@BuildStream-Migration-Bot
Copy link

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.

Problems

  1. Command options that take option arguments are not sensibly named, e.g. The bst build --track option shows:
    image

    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:

    image

    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:

    image
@BuildStream-Migration-Bot BuildStream-Migration-Bot added bug Something isn't working documentation Improvements or additions to documentation has attachment labels Feb 2, 2021
@BuildStream-Migration-Bot
Copy link
Author

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

@BuildStream-Migration-Bot
Copy link
Author

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.

@BuildStream-Migration-Bot
Copy link
Author

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

@BuildStream-Migration-Bot
Copy link
Author

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.

@BuildStream-Migration-Bot
Copy link
Author

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

changed the description

@BuildStream-Migration-Bot
Copy link
Author

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

changed the description

@BuildStream-Migration-Bot
Copy link
Author

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

changed the description

@BuildStream-Migration-Bot
Copy link
Author

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

changed the description

@BuildStream-Migration-Bot
Copy link
Author

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

@BuildStream-Migration-Bot
Copy link
Author

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

@BuildStream-Migration-Bot
Copy link
Author

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

@BuildStream-Migration-Bot
Copy link
Author

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

removed milestone

@BuildStream-Migration-Bot
Copy link
Author

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.

@BuildStream-Migration-Bot
Copy link
Author

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.

@BuildStream-Migration-Bot
Copy link
Author

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

mentioned in commit e624b2d791ee16e0a0a14c643904c3c0a4bad50c

@BuildStream-Migration-Bot
Copy link
Author

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

mentioned in merge request !1824

@BuildStream-Migration-Bot
Copy link
Author

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

mentioned in commit 8edf482

@BuildStream-Migration-Bot
Copy link
Author

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

closed via merge request !1824

@BuildStream-Migration-Bot
Copy link
Author

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

mentioned in commit 71179f8

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
bug Something isn't working documentation Improvements or additions to documentation
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@BuildStream-Migration-Bot