commit 4b90bd04a1b48780957e4d8435cb2fd236604aee Author: Damian Johnson <atagar@torproject.org> Date: Tue Nov 24 09:30:41 2015 -0800 Example for using our manual module Expanding our manual module's header docs. Describing how our various methods of getting manual information differ and adding an example. --- docs/_static/example/manual_config_options.py | 30 ++++++++++++++++++++++++ docs/_static/manual_output.png | Bin 0 -> 54570 bytes stem/manual.py | 31 ++++++++++++++++++++++--- 3 files changed, 58 insertions(+), 3 deletions(-) diff --git a/docs/_static/example/manual_config_options.py b/docs/_static/example/manual_config_options.py new file mode 100644 index 0000000..964ff52 --- /dev/null +++ b/docs/_static/example/manual_config_options.py @@ -0,0 +1,30 @@ +from stem.manual import Manual +from stem.util import term + +try: + print("Downloading tor's manual information, please wait...") + manual = Manual.from_remote() + print(" done\n") +except IOError as exc: + print(" unsuccessful (%s), using information provided with stem\n" % exc) + manual = Manual.from_cache() # fall back to our bundled manual information + +print('Which tor configuration would you like to learn about? (press ctrl+c to quit)\n') + +try: + while True: + requested_option = raw_input('> ').strip() + + if requested_option: + if requested_option in manual.config_options: + option = manual.config_options[requested_option] + print(term.format('%s %s' % (option.name, option.usage), term.Color.GREEN, term.Attr.BOLD)) + print(term.format(option.summary, term.Color.GREEN)) # brief description provided by stem + + print(term.format('\nFull Description:\n', term.Color.GREEN, term.Attr.BOLD)) + print(term.format(option.description + '\n', term.Color.GREEN)) + else: + print(term.format("Sorry, we don't have any information about %s. Are you sure it's an option?" % requested_option, term.Color.RED)) +except KeyboardInterrupt: + pass # user pressed ctrl+c + diff --git a/docs/_static/manual_output.png b/docs/_static/manual_output.png new file mode 100644 index 0000000..4fccd94 Binary files /dev/null and b/docs/_static/manual_output.png differ diff --git a/stem/manual.py b/stem/manual.py index 4f51d1f..1e2a8f1 100644 --- a/stem/manual.py +++ b/stem/manual.py @@ -2,8 +2,33 @@ # See LICENSE for licensing information """ -Provides information available about Tor from `its manual -<https://www.torproject.org/docs/tor-manual.html.en>`_. +Information available about Tor from `its manual +<https://www.torproject.org/docs/tor-manual.html.en>`_. This provides three +methods of getting this information... + +* :func:`~stem.manual.Manual.from_cache` provides manual content bundled with + Stem. This is the fastest and most reliable method but only as up-to-date as + Stem's release. + +* :func:`~stem.manual.Manual.from_man` reads Tor's local man page for + information about it. + +* :func:`~stem.manual.Manual.from_remote` fetches the latest manual information + remotely. This is the slowest and least reliable method but provides the most + recent information about Tor. + +Manual information includes arguments, signals, and probably most usefully the +torrc configuration options. For example, say we want a little script that told +us what our torrc options do... + +.. literalinclude:: /_static/example/manual_config_options.py + :language: python + +| + +.. image:: /_static/manual_output.png + +| **Module Overview:** @@ -263,7 +288,7 @@ class Manual(object): with tempfile.NamedTemporaryFile() as tmp: download_man_page(file_handle = tmp, timeout = timeout) - return Manual.from_man(tmp) + return Manual.from_man(tmp.name) def _get_categories(content):