[tor-commits] [stem/master] Example for using our manual module

[atagar at torproject.org]

commit 4b90bd04a1b48780957e4d8435cb2fd236604aee
Author: Damian Johnson <atagar at 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):