Auto-generate much of the RBTools command documentation.
Review Request #6711 — Created Dec. 31, 2014 and submitted
Our RBTools command docs were getting stale, particularly as we added new common sets of command line arguments. The docs were largely copy/pastes that were getting out of sync. This also made it much harder to write new doc pages for new commands. We now have a new set of Sphinx/ReST directives for automatically populating a page with up-to-date information on commands. The "rbt-command" directive sets up the page state, anchors, and the current "program domain" used for linking to options. "rbt-command-usage" outputs usage information, similar to what's on the command line when using --help. "rbt-command-options" outputs all the options for the commands. This directive takes all the help text, extended help text, meta variables, version metadata, configuration keys, etc. from all registered options and option groups for a command and outputs it in a clear way. The documentation now provides a better idea of what arguments the various options expect, their default values (if any), and how to change defaults (if supported). It also states whether an option is scheduled for removal, or when it was added.
Went through every doc page and inspected the list of options and the
usage, comparing to the previous versions of the pages.Tested that links to the commands pages were working.
Built a clean docs build and didn't see any new warnings.
Review request changed
- Change Summary:
-
Fixed unused imports.
- Commit:
-
ef75f05cc3570535b4554bcdf6013d549f2b98215e0a8d7f06473f6f5a73a3e16b0ff87e2a4cfa10
- Diff:
-
Revision 2 (+353 -880)
-
Tool: PEP8 Style Checker Processed Files: docs/rbtools/_ext/rbt_commands.py docs/rbtools/conf.py Ignored Files: docs/rbtools/rbt/commands/post.rst docs/rbtools/rbt/commands/list-repo-types.rst docs/rbtools/rbt/commands/close.rst docs/rbtools/rbt/commands/publish.rst docs/rbtools/rbt/configuration.rst docs/rbtools/rbt/commands/attach.rst docs/rbtools/rbt/commands/patch.rst docs/rbtools/rbt/commands/clear-cache.rst docs/rbtools/_ext/__init__.py docs/rbtools/rbt/commands/status.rst docs/rbtools/rbt/commands/diff.rst docs/rbtools/rbt/commands/setup-repo.rst docs/rbtools/rbt/commands/api-get.rst Tool: Pyflakes Processed Files: docs/rbtools/_ext/rbt_commands.py docs/rbtools/conf.py Ignored Files: docs/rbtools/rbt/commands/post.rst docs/rbtools/rbt/commands/list-repo-types.rst docs/rbtools/rbt/commands/close.rst docs/rbtools/rbt/commands/publish.rst docs/rbtools/rbt/configuration.rst docs/rbtools/rbt/commands/attach.rst docs/rbtools/rbt/commands/patch.rst docs/rbtools/rbt/commands/clear-cache.rst docs/rbtools/_ext/__init__.py docs/rbtools/rbt/commands/status.rst docs/rbtools/rbt/commands/diff.rst docs/rbtools/rbt/commands/setup-repo.rst docs/rbtools/rbt/commands/api-get.rst
Review request changed
- Change Summary:
-
Removed unnecessary parens.
- Commit:
-
5e0a8d7f06473f6f5a73a3e16b0ff87e2a4cfa10802911fdfcbd73a65b793b7cf1e8310909fd9e5d
- Diff:
-
Revision 3 (+354 -881)
-
Tool: Pyflakes Processed Files: docs/rbtools/_ext/rbt_commands.py rbtools/commands/post.py docs/rbtools/conf.py Ignored Files: docs/rbtools/rbt/commands/post.rst docs/rbtools/rbt/commands/list-repo-types.rst docs/rbtools/rbt/commands/close.rst docs/rbtools/rbt/commands/publish.rst docs/rbtools/rbt/configuration.rst docs/rbtools/rbt/commands/attach.rst docs/rbtools/rbt/commands/patch.rst docs/rbtools/rbt/commands/clear-cache.rst docs/rbtools/_ext/__init__.py docs/rbtools/rbt/commands/status.rst docs/rbtools/rbt/commands/diff.rst docs/rbtools/rbt/commands/setup-repo.rst docs/rbtools/rbt/commands/api-get.rst Tool: PEP8 Style Checker Processed Files: docs/rbtools/_ext/rbt_commands.py rbtools/commands/post.py docs/rbtools/conf.py Ignored Files: docs/rbtools/rbt/commands/post.rst docs/rbtools/rbt/commands/list-repo-types.rst docs/rbtools/rbt/commands/close.rst docs/rbtools/rbt/commands/publish.rst docs/rbtools/rbt/configuration.rst docs/rbtools/rbt/commands/attach.rst docs/rbtools/rbt/commands/patch.rst docs/rbtools/rbt/commands/clear-cache.rst docs/rbtools/_ext/__init__.py docs/rbtools/rbt/commands/status.rst docs/rbtools/rbt/commands/diff.rst docs/rbtools/rbt/commands/setup-repo.rst docs/rbtools/rbt/commands/api-get.rst
Review request changed
- Change Summary:
-
The auto-generated sections are now guaranteed to be at the right level in the tree.
- Commit:
-
802911fdfcbd73a65b793b7cf1e8310909fd9e5d590993a2cff94c3d02ada305808d01c67a061c7e
- Diff:
-
Revision 4 (+370 -880)
-
Tool: PEP8 Style Checker Processed Files: docs/rbtools/_ext/rbt_commands.py docs/rbtools/conf.py Ignored Files: docs/rbtools/rbt/commands/post.rst docs/rbtools/rbt/commands/list-repo-types.rst docs/rbtools/rbt/commands/close.rst docs/rbtools/rbt/commands/publish.rst docs/rbtools/rbt/configuration.rst docs/rbtools/rbt/commands/attach.rst docs/rbtools/rbt/commands/patch.rst docs/rbtools/rbt/commands/clear-cache.rst docs/rbtools/_ext/__init__.py docs/rbtools/rbt/commands/status.rst docs/rbtools/rbt/commands/diff.rst docs/rbtools/rbt/commands/setup-repo.rst docs/rbtools/rbt/commands/api-get.rst Tool: Pyflakes Processed Files: docs/rbtools/_ext/rbt_commands.py docs/rbtools/conf.py Ignored Files: docs/rbtools/rbt/commands/post.rst docs/rbtools/rbt/commands/list-repo-types.rst docs/rbtools/rbt/commands/close.rst docs/rbtools/rbt/commands/publish.rst docs/rbtools/rbt/configuration.rst docs/rbtools/rbt/commands/attach.rst docs/rbtools/rbt/commands/patch.rst docs/rbtools/rbt/commands/clear-cache.rst docs/rbtools/_ext/__init__.py docs/rbtools/rbt/commands/status.rst docs/rbtools/rbt/commands/diff.rst docs/rbtools/rbt/commands/setup-repo.rst docs/rbtools/rbt/commands/api-get.rst
Tool: Pyflakes Processed Files: docs/rbtools/_ext/rbt_commands.py docs/rbtools/conf.py Ignored Files: docs/rbtools/rbt/commands/post.rst docs/rbtools/rbt/commands/list-repo-types.rst docs/rbtools/rbt/commands/close.rst docs/rbtools/rbt/commands/publish.rst docs/rbtools/rbt/configuration.rst docs/rbtools/rbt/commands/attach.rst docs/rbtools/rbt/commands/patch.rst docs/rbtools/rbt/commands/clear-cache.rst docs/rbtools/_ext/__init__.py docs/rbtools/rbt/commands/status.rst docs/rbtools/rbt/commands/diff.rst docs/rbtools/rbt/commands/setup-repo.rst docs/rbtools/rbt/commands/api-get.rst Tool: PEP8 Style Checker Processed Files: docs/rbtools/_ext/rbt_commands.py docs/rbtools/conf.py Ignored Files: docs/rbtools/rbt/commands/post.rst docs/rbtools/rbt/commands/list-repo-types.rst docs/rbtools/rbt/commands/close.rst docs/rbtools/rbt/commands/publish.rst docs/rbtools/rbt/configuration.rst docs/rbtools/rbt/commands/attach.rst docs/rbtools/rbt/commands/patch.rst docs/rbtools/rbt/commands/clear-cache.rst docs/rbtools/_ext/__init__.py docs/rbtools/rbt/commands/status.rst docs/rbtools/rbt/commands/diff.rst docs/rbtools/rbt/commands/setup-repo.rst docs/rbtools/rbt/commands/api-get.rst