[tor-commits] [stem/master] Module providing tor manual information

[atagar at torproject.org]

commit 180d59c6a7fb75b49d64775ad92f0c0af9d30686
Merge: 4ecaa61 bd86f10
Author: Damian Johnson <atagar at torproject.org>
Date:   Sun Dec 6 13:26:49 2015 -0800

    Module providing tor manual information
    
    For years Nyx (aka arm) has done a neat trick where we describe what torrc
    options do and how they're used (ie, what you get with 'man tor'). To do this
    Nyx had its own cobbled together parser for tor's man page. Clearly a hack, but
    it worked.
    
    While that was all well and good, but we can clearly do better. Introducing
    'stem.manual' which, besides filling Nyx's needs, provides...
    
      * Tor test coverage. This adds several integration tests to confirm tor can
        properly build a valid man page.
    
      * Provides all Stem users with three methods for getting tor manual
        information...
    
        a. from_cache() - Retrieves information bundled with Stem. This is only as
           up to date as Stem itself, but the fastest and most reliable method.
    
        b. from_man() - Parses information from the local system by running 'man
           tor'. Still fast, but obviously requires tor's man page to be present.
    
        c. from_remote() - Retrieves the latest manual information from tor's git
           repository. This is slow and shouldn't be used without a fallback, but
           provides the most up-to-date manual information.
    
        These methods can be chained together as fallbacks. For instance see...
    
           https://stem.torproject.org/api/manual.html
    
      * Along with tor's manual information we provide brief, more user-friendly
        descriptions of all tor's configuration options.
    
      * Parser is much improved over Nyx's. In particular the stem.manual module
        has vastly improved performance, test coverage, and updated summary
        information.

 cache_manual.py                               |   56 +
 docs/_static/example/manual_config_options.py |   30 +
 docs/_static/manual_output.png                |  Bin 0 -> 54570 bytes
 docs/api.rst                                  |    1 +
 docs/api/manual.rst                           |    5 +
 docs/change_log.rst                           |    2 +
 docs/contents.rst                             |    1 +
 run_tests.py                                  |    6 +-
 setup.py                                      |    3 +-
 stem/cached_tor_manual.cfg                    | 1828 +++++++++++++++++++++++++
 stem/control.py                               |  109 +-
 stem/descriptor/hidden_service_descriptor.py  |   32 +-
 stem/descriptor/microdescriptor.py            |    3 +
 stem/descriptor/networkstatus.py              |   40 +-
 stem/descriptor/reader.py                     |    1 +
 stem/descriptor/remote.py                     |    5 +-
 stem/descriptor/router_status_entry.py        |   12 +
 stem/descriptor/server_descriptor.py          |    6 +
 stem/exit_policy.py                           |    9 +
 stem/manual.py                                |  584 ++++++++
 stem/response/events.py                       |    3 +
 stem/settings.cfg                             |  352 +++++
 stem/util/conf.py                             |   21 +-
 stem/util/connection.py                       |   32 +-
 stem/util/system.py                           |    8 +-
 stem/util/test_tools.py                       |   20 +-
 stem/version.py                               |    3 +
 test/integ/installation.py                    |   78 +-
 test/integ/manual.py                          |  336 +++++
 test/integ/tor.1_with_unknown                 |   51 +
 test/settings.cfg                             |    4 +
 test/unit/manual.py                           |  236 ++++
 test/unit/tor_man_example                     |  227 +++
 33 files changed, 3967 insertions(+), 137 deletions(-)