Auto-generate much of the RBTools command documentation.

Review Request #6711 — Created Dec. 31, 2014 and submitted

Information

RBTools
master
590993a...

Reviewers

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.

Description From Last Updated

'directives' imported but unused

reviewbotreviewbot

'Cmdoption' imported but unused

reviewbotreviewbot

The parens here aren't necessary.

daviddavid
reviewbot
  1. 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
    
    
  2. docs/rbtools/_ext/rbt_commands.py (Diff revision 1)
     
     
    Show all issues
     'directives' imported but unused
    
  3. docs/rbtools/_ext/rbt_commands.py (Diff revision 1)
     
     
    Show all issues
     'Cmdoption' imported but unused
    
  4. 
      
chipx86
reviewbot
  1. 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
    
    
  2. 
      
david
  1. 
      
  2. docs/rbtools/_ext/rbt_commands.py (Diff revision 2)
     
     
    Show all issues

    The parens here aren't necessary.

  3. 
      
chipx86
reviewbot
  1. 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
    
    
  2. 
      
chipx86
reviewbot
  1. 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
    
    
  2. 
      
david
  1. Ship It!
  2. 
      
chipx86
Review request changed
Status:
Completed
Change Summary:
Pushed to master (4b32e4b)