[docs] Automatically generate CLI documentation #16851
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Command-line usage information was previously only available to users who had successfully installed wptrunner. Consuming the information in that form (e.g. navigating between sub-commands, scrolling through pages of content and searching for keywords) also required some proficiency with the command-line. Extend the documentation build process to include this information in the project website. This makes it easier to consume for those with limited experience using the command-line, and in particular, it adds the content to the data indexed by the website's "search" feature. Because this content is generated from the state of the interface, it avoids the need to maintain documentation separately. This is implemented via a new code path that eagerly load wptrunner's complete command-line interface. The new `create_complete_parser` is consumed by the `sphinx-argparse` module to produce the rendered documentation.
gsnedders
approved these changes
May 20, 2019
There was a problem hiding this comment.
This seems like a good first iteration to me; really we want to be smarter about grouping the command line args, and make it clear which only apply to specific runners, and probably to be less verbose just calling ./wpt run --help (because OH DEAR GOD information overload), but that all already applies to --help and this is itself an improvement for the website.
|
Awesome, @gsnedders, thanks for looking this over! Would you like me to get approval from anyone else? |
|
I'm happy not to, especially when nobody else has commented in over a week. :) |
marcoscaceres
pushed a commit
that referenced
this pull request
Jul 23, 2019
Command-line usage information was previously only available to users who had successfully installed wptrunner. Consuming the information in that form (e.g. navigating between sub-commands, scrolling through pages of content and searching for keywords) also required some proficiency with the command-line. Extend the documentation build process to include this information in the project website. This makes it easier to consume for those with limited experience using the command-line, and in particular, it adds the content to the data indexed by the website's "search" feature. Because this content is generated from the state of the interface, it avoids the need to maintain documentation separately. This is implemented via a new code path that eagerly load wptrunner's complete command-line interface. The new `create_complete_parser` is consumed by the `sphinx-argparse` module to produce the rendered documentation.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Command-line usage information was previously only available to users
who had successfully installed wptrunner. Consuming the information in
that form (e.g. navigating between sub-commands, scrolling through pages
of content and searching for keywords) also required some proficiency
with the command-line.
Extend the documentation build process to include this information in
the project website. This makes it easier to consume for those with
limited experience using the command-line, and in particular, it adds
the content to the data indexed by the website's "search" feature.
Because this content is generated from the state of the interface, it
avoids the need to maintain documentation separately.
This is implemented via a new code path that eagerly load wptrunner's
complete command-line interface. The new
create_complete_parserisconsumed by the
sphinx-argparsemodule to produce the rendereddocumentation.
Previously discussed in bocoup/wpt-docs#12
The wptrunner CLI is built lazily based on the subcommand being executed. Even then, the task of argument parsing is split across unrelated
argparseinstances. These two details resist documentation generation (at least in the terms expected by thesphinx-argparsemodule).Facilitating this work required an artificial code path. I'm sensitive to creating branches that aren't used by contributors, but given the small size of the new function, I think the documentation may be valuable enough to justify the maintenance burden.
Here's what the new page looks like:
Like any other content on the Sphinx-powered site, it is indexed by the client-side "search" feature.
And the user's query is highlighted on the page itself