search

bocoup / wpt-docs

A clone of the web-platform-tests project to collaborate on documentation reorganization
https://wpt-docs.readthedocs.io
Other
1 stars 0 forks source link

[docs] Automatically generate CLI documentation #10

Closed jugglinmike closed 5 years ago

jugglinmike commented 5 years ago

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.

This is one way we can automatically include documentation for the wpt command-line interface in the documentation website.

The wptrunner CLI is built lazily based on the subcommand being executed. Even then, the task of argument parsing is split across unrelated argparse instances. These two details resist documentation generation (at least in the terms expected by the sphinx-argparse module).

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 page looks like by default. (We should certainly tweak the appearance, but I'd like to verify that the high-level approach is acceptable before diving in to that.)

2019-03-27-docs-cli-top

Like any other content on the Sphinx-powered site, it is indexed by the client-side "search" feature.

2019-03-27-docs-cli-search-results

And the user's query is highlighted on the page itself

2019-03-27-docs-cli-search-highlight-1

2019-03-27-docs-cli-search-highlight-2

Depends on gh-7.

jugglinmike commented 5 years ago

@jgraham the final commit on this branch is what I'm referring to in this pull request's description. What do you think about maintaining code like this in wptrunner?

jgraham commented 5 years ago

That change looks fine; not sure why it's not a PR against upstream though, since reviewing a big-bang commit with all these changes in won't end up with meaningful review. I'm not sure how wptrunner is related though; where wptrunner is exposing something different to the wpt subcommands that wrap it, the wpt variants are the ones that should be documented.

jugglinmike commented 5 years ago

Since this approach involves executing a bunch of wptrunner, I couldn't be sure it would work on the system provided by readthedocs.org. I merged this to find out, and it does in fact work.

GitHub doesn't allow merged pull requests to be re-opened (regardless of the state of the base branch), so I created a new pull request to continue the review: gh-12.