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.

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

[docs] Automatically generate CLI documentation #16851

Merged
merged 1 commit into from May 25, 2019

Conversation

@jugglinmike
Copy link
Contributor

jugglinmike commented May 15, 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.


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 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 new page looks like:

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

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.
Copy link
Contributor

gsnedders left a 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.

@jugglinmike
Copy link
Contributor Author

jugglinmike commented May 23, 2019

Awesome, @gsnedders, thanks for looking this over! Would you like me to get approval from anyone else?

@gsnedders
Copy link
Contributor

gsnedders commented May 25, 2019

I'm happy not to, especially when nobody else has commented in over a week. :)

@gsnedders gsnedders merged commit 3149a43 into web-platform-tests:master May 25, 2019
15 checks passed
15 checks passed
manifest-build-and-tag manifest-build-and-tag
Details
website-build-and-publish website-build-and-publish
Details
Azure Pipelines Build #20190515.125 succeeded
Details
Azure Pipelines (./wpt test-jobs) ./wpt test-jobs succeeded
Details
Azure Pipelines (affected tests (Safari Technology Preview)) affected tests (Safari Technology Preview) succeeded
Details
Azure Pipelines (affected tests without changes (Safari Technology Preview)) affected tests without changes (Safari Technology Preview) succeeded
Details
Azure Pipelines (infrastructure/ tests (macOS)) infrastructure/ tests (macOS) succeeded
Details
Azure Pipelines (tools/ unittests (macOS)) tools/ unittests (macOS) succeeded
Details
Azure Pipelines (tools/wpt/ tests (macOS)) tools/wpt/ tests (macOS) succeeded
Details
Azure Pipelines (tools/wptrunner/ unittests (macOS)) tools/wptrunner/ unittests (macOS) succeeded
Details
Azure Pipelines (wpt.fyi hook: safari-preview-affected-tests) wpt.fyi hook: safari-preview-affected-tests succeeded
Details
Azure Pipelines (wpt.fyi hook: safari-preview-affected-tests-without-changes) wpt.fyi hook: safari-preview-affected-tests-without-changes succeeded
Details
Taskcluster (pull_request) TaskGroup: success
Details
staging.wpt.fyi - safari[experimental] Safari results
Details
wpt.fyi - safari[experimental] Safari results
Details
marcoscaceres added 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
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

4 participants
You can’t perform that action at this time.