[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [stem/master] Moving tutorial to dedicated page



commit 8c767d35514ca345d051c94246668e97151d1c73
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
Date:   Sun Oct 14 18:09:09 2012 -0700

    Moving tutorial to dedicated page
    
    Beginning of my grand scheme to make stem's front page a simple listing of its
    sections (tutorial, API, release notes, download, etc).
    
    Moved the tutorial to its own page with a summary of the tutorials listed at
    the top. The tutorial is linked from the main page by an image link.
---
 docs/_static/buttons/tutorial.png        |  Bin 0 -> 12908 bytes
 docs/_static/buttons/unused/tutorial.xcf |  Bin 0 -> 32568 bytes
 docs/index.rst                           |  122 +---------------------------
 docs/tutorial.rst                        |  129 ++++++++++++++++++++++++++++++
 4 files changed, 133 insertions(+), 118 deletions(-)

diff --git a/docs/_static/buttons/tutorial.png b/docs/_static/buttons/tutorial.png
new file mode 100644
index 0000000..65e0f38
Binary files /dev/null and b/docs/_static/buttons/tutorial.png differ
diff --git a/docs/_static/buttons/unused/tutorial.xcf b/docs/_static/buttons/unused/tutorial.xcf
new file mode 100644
index 0000000..5e9afed
Binary files /dev/null and b/docs/_static/buttons/unused/tutorial.xcf differ
diff --git a/docs/index.rst b/docs/index.rst
index 35806d2..5cc754c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -3,124 +3,8 @@ Welcome to Stem!
 
 Stem is a python controller library for `Tor <https://www.torproject.org/>`_. Like its predecessor, `TorCtl <https://www.torproject.org/getinvolved/volunteer.html.en#project-torctl>`_, it uses Tor's `control protocol <https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt>`_ to help developers program against the Tor process, enabling them to build things similar to `Vidalia <https://www.torproject.org/getinvolved/volunteer.html.en#project-vidalia>`_ and `arm <http://www.atagar.com/arm/>`_.
 
-Getting started with any new library can be rather daunting, so lets get our feet wet by jumping straight in with a tutorial...
-
-The Little Relay that Could
----------------------------
-
-Lets say you just set up your very first `Tor relay <https://www.torproject.org/docs/tor-doc-relay.html.en>`_. Thank you! Now you want to write a script that tells you how much it is being used.
-
-First, for any script we write to be able to talk with our relay it'll need to have a control port available. This is a port that's usually only available on localhost and protected by either a password or authentication cookie.
-
-Look at your `torrc <https://www.torproject.org/docs/faq.html.en#torrc>`_ for the following configuration options...
-
-::
-
-  # This provides a port for the script we write to talk to. If you set this
-  # then be sure to also have either set the CookieAuthentication flag *or*
-  # provide a HashedControlPassword!
-  
-  ControlPort 9051
-  
-  # This will make Tor write an authentication cookie file. Anything that can
-  # read that file can connect to Tor. If you're going to run this script with
-  # the same user as Tor then this is the easiest method of authentication to
-  # use.
-  
-  CookieAuthentication 1
-  
-  # Alternatively we can authenticate with a password. To set a password first
-  # get its hash...
-  #
-  # % tor --hash-password "my_password"
-  # 16:E600ADC1B52C80BB6022A0E999A7734571A451EB6AE50FED489B72E3DF
-  #
-  # ... and use that for the HashedControlPassword in our torrc.
-  
-  HashedControlPassword 16:E600ADC1B52C80BB6022A0E999A7734571A451EB6AE50FED489B72E3DF
-
-You'll need to restart Tor or issue a SIGHUP for these new settings to take effect. Now lets write a script that tells us how many bytes Tor has sent and received...
-
-::
-
-  from stem.control import Controller
-  
-  controller = Controller.from_port(control_port = 9051)
-  controller.authenticate() # provide the password here if you set one
-  
-  bytes_read = controller.get_info("traffic/read")
-  bytes_written = controller.get_info("traffic/written")
-  
-  print "My Tor relay has read %s bytes and written %s." % (bytes_read, bytes_written)
-  controller.close()
-
-::
-
-  % python example.py 
-  My Tor relay has read 33406 bytes and written 29649.
-
-Congratulations! You've just written your first controller script.
-
-Mirror Mirror on the Wall
--------------------------
-
-A script that tells us our contributed bandwidth is neat and all, but now lets figure out who the *biggest* exit relays are.
-
-Information about the Tor relay network come from documents called **descriptors**. Descriptors can come from a few things...
-
-1. The Tor control port with GETINFO options like **desc/all-recent** and **ns/all**.
-2. Files in Tor's data directory, like **cached-descriptors** and **cached-consensus**.
-3. The descriptor archive on `Tor's metrics site <https://metrics.torproject.org/data.html>`_.
-
-We've already used the control port, so for this example we'll use the cached files directly. First locate Tor's data directory. If your torrc has a DataDirectory line then that's the spot. If not then check Tor's man page for the default location.
-
-Tor has several descriptor types. For bandwidth information we'll go to the server descriptors, which are located in the **cached-descriptors** file. These have somewhat infrequently changing information published by the relays themselves.
-
-To read this file we'll use the :class:`~stem.descriptor.reader.DescriptorReader`, a class designed to read descriptor files. The **cached-descriptors** is full of server descriptors, so the reader will provide us with :class:`~stem.descriptor.server_descriptor.RelayDescriptor` instances (a :class:`~stem.descriptor.server_descriptor.ServerDescriptor` subclass for relays).
-
-::
-
-  import sys
-  from stem.descriptor.reader import DescriptorReader
-  
-  bw_to_relay = {} # mapping of observed bandwidth to the relay nicknames
-  
-  with DescriptorReader(["/home/atagar/.tor/cached-descriptors"]) as reader:
-    for desc in reader:
-      if desc.exit_policy.is_exiting_allowed():
-        bw_to_relay.setdefault(desc.observed_bandwidth, []).append(desc.nickname)
-  
-  sorted_bw = sorted(bw_to_relay.keys(), reverse = True)
-  
-  # prints the top fifteen relays
-  
-  count = 1
-  for bw_value in sorted_bw:
-    for nickname in bw_to_relay[bw_value]:
-      print "%i. %s (%i bytes/s)" % (count, nickname, bw_value)
-      count += 1
-      
-      if count > 15:
-        sys.exit()
-
-::
-
-  % python example.py 
-  1. herngaard (42939655 bytes/s)
-  2. chaoscomputerclub19 (42402911 bytes/s)
-  3. chaoscomputerclub18 (41967097 bytes/s)
-  4. chaoscomputerclub20 (40882989 bytes/s)
-  5. wannabe (40514411 bytes/s)
-  6. dorrisdeebrown (40349829 bytes/s)
-  7. manning2 (40057719 bytes/s)
-  8. chaoscomputerclub21 (38701399 bytes/s)
-  9. TorLand1 (37983627 bytes/s)
-  10. bolobolo1 (37676580 bytes/s)
-  11. manning1 (37117034 bytes/s)
-  12. gorz (35760527 bytes/s)
-  13. ndnr1 (26595129 bytes/s)
-  14. politkovskaja2 (26149682 bytes/s)
-  15. wau (25929953 bytes/s)
+.. image:: /_static/buttons/tutorial.png
+   :target: tutorial.html
 
 :mod:`stem.connection`
 ----------------------
@@ -174,3 +58,5 @@ Indices and tables
 
 *Last updated:* |today|
 
+
+
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
new file mode 100644
index 0000000..9cb1414
--- /dev/null
+++ b/docs/tutorial.rst
@@ -0,0 +1,129 @@
+Tutorial
+========
+
+Getting started with any new library can be rather daunting, so lets get our feet wet by jumping straight in with a tutorial...
+
+* :ref:`the-little-relay-that-could` - Hello world with the control port.
+* :ref:`mirror-mirror-on-the-wall` - Querying information about the Tor network.
+
+.. _the-little-relay-that-could:
+
+The Little Relay that Could
+---------------------------
+
+Lets say you just set up your very first `Tor relay <https://www.torproject.org/docs/tor-doc-relay.html.en>`_. Thank you! Now you want to write a script that tells you how much it is being used.
+
+First, for any script we write to be able to talk with our relay it'll need to have a control port available. This is a port that's usually only available on localhost and protected by either a password or authentication cookie.
+
+Look at your `torrc <https://www.torproject.org/docs/faq.html.en#torrc>`_ for the following configuration options...
+
+::
+
+  # This provides a port for the script we write to talk to. If you set this
+  # then be sure to also have either set the CookieAuthentication flag *or*
+  # provide a HashedControlPassword!
+  
+  ControlPort 9051
+  
+  # This will make Tor write an authentication cookie file. Anything that can
+  # read that file can connect to Tor. If you're going to run this script with
+  # the same user as Tor then this is the easiest method of authentication to
+  # use.
+  
+  CookieAuthentication 1
+  
+  # Alternatively we can authenticate with a password. To set a password first
+  # get its hash...
+  #
+  # % tor --hash-password "my_password"
+  # 16:E600ADC1B52C80BB6022A0E999A7734571A451EB6AE50FED489B72E3DF
+  #
+  # ... and use that for the HashedControlPassword in our torrc.
+  
+  HashedControlPassword 16:E600ADC1B52C80BB6022A0E999A7734571A451EB6AE50FED489B72E3DF
+
+You'll need to restart Tor or issue a SIGHUP for these new settings to take effect. Now lets write a script that tells us how many bytes Tor has sent and received...
+
+::
+
+  from stem.control import Controller
+  
+  controller = Controller.from_port(control_port = 9051)
+  controller.authenticate() # provide the password here if you set one
+  
+  bytes_read = controller.get_info("traffic/read")
+  bytes_written = controller.get_info("traffic/written")
+  
+  print "My Tor relay has read %s bytes and written %s." % (bytes_read, bytes_written)
+  controller.close()
+
+::
+
+  % python example.py 
+  My Tor relay has read 33406 bytes and written 29649.
+
+Congratulations! You've just written your first controller script.
+
+.. _mirror-mirror-on-the-wall:
+
+Mirror Mirror on the Wall
+-------------------------
+
+A script that tells us our contributed bandwidth is neat and all, but now lets figure out who the *biggest* exit relays are.
+
+Information about the Tor relay network come from documents called **descriptors**. Descriptors can come from a few things...
+
+1. The Tor control port with GETINFO options like **desc/all-recent** and **ns/all**.
+2. Files in Tor's data directory, like **cached-descriptors** and **cached-consensus**.
+3. The descriptor archive on `Tor's metrics site <https://metrics.torproject.org/data.html>`_.
+
+We've already used the control port, so for this example we'll use the cached files directly. First locate Tor's data directory. If your torrc has a DataDirectory line then that's the spot. If not then check Tor's man page for the default location.
+
+Tor has several descriptor types. For bandwidth information we'll go to the server descriptors, which are located in the **cached-descriptors** file. These have somewhat infrequently changing information published by the relays themselves.
+
+To read this file we'll use the :class:`~stem.descriptor.reader.DescriptorReader`, a class designed to read descriptor files. The **cached-descriptors** is full of server descriptors, so the reader will provide us with :class:`~stem.descriptor.server_descriptor.RelayDescriptor` instances (a :class:`~stem.descriptor.server_descriptor.ServerDescriptor` subclass for relays).
+
+::
+
+  import sys
+  from stem.descriptor.reader import DescriptorReader
+  
+  bw_to_relay = {} # mapping of observed bandwidth to the relay nicknames
+  
+  with DescriptorReader(["/home/atagar/.tor/cached-descriptors"]) as reader:
+    for desc in reader:
+      if desc.exit_policy.is_exiting_allowed():
+        bw_to_relay.setdefault(desc.observed_bandwidth, []).append(desc.nickname)
+  
+  sorted_bw = sorted(bw_to_relay.keys(), reverse = True)
+  
+  # prints the top fifteen relays
+  
+  count = 1
+  for bw_value in sorted_bw:
+    for nickname in bw_to_relay[bw_value]:
+      print "%i. %s (%i bytes/s)" % (count, nickname, bw_value)
+      count += 1
+      
+      if count > 15:
+        sys.exit()
+
+::
+
+  % python example.py 
+  1. herngaard (42939655 bytes/s)
+  2. chaoscomputerclub19 (42402911 bytes/s)
+  3. chaoscomputerclub18 (41967097 bytes/s)
+  4. chaoscomputerclub20 (40882989 bytes/s)
+  5. wannabe (40514411 bytes/s)
+  6. dorrisdeebrown (40349829 bytes/s)
+  7. manning2 (40057719 bytes/s)
+  8. chaoscomputerclub21 (38701399 bytes/s)
+  9. TorLand1 (37983627 bytes/s)
+  10. bolobolo1 (37676580 bytes/s)
+  11. manning1 (37117034 bytes/s)
+  12. gorz (35760527 bytes/s)
+  13. ndnr1 (26595129 bytes/s)
+  14. politkovskaja2 (26149682 bytes/s)
+  15. wau (25929953 bytes/s)
+



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits