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

[tor-commits] [stem/master] Moving tutorials to sub-pages



commit f4d2b20b2d954852faa59d39ce9f38f7cb11dcd2
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
Date:   Mon Feb 18 22:12:01 2013 -0800

    Moving tutorials to sub-pages
    
    Making pages for each of the tutorials and making tutorial.rst a pretty listing
    similar to the download page. This should hopefully make this page far more
    approachable by newcomers.
---
 docs/_static/label/mirror_mirror_on_the_wall.png   |  Bin 0 -> 2675 bytes
 .../label/resources/mirror_mirror_on_the_wall.xcf  |  Bin 0 -> 7035 bytes
 .../resources/the_little_relay_that_could.xcf      |  Bin 0 -> 7273 bytes
 docs/_static/label/the_little_relay_that_could.png |  Bin 0 -> 3162 bytes
 docs/_static/section/tutorial/mirror.png           |  Bin 0 -> 2985 bytes
 docs/_static/section/tutorial/train.png            |  Bin 0 -> 9887 bytes
 docs/contents.rst                                  |    3 +
 docs/tutorial.rst                                  |  168 ++++----------------
 docs/tutorial/mirror_mirror_on_the_wall.rst        |   83 ++++++++++
 docs/tutorial/the_little_relay_that_could.rst      |   56 +++++++
 10 files changed, 172 insertions(+), 138 deletions(-)

diff --git a/docs/_static/label/mirror_mirror_on_the_wall.png b/docs/_static/label/mirror_mirror_on_the_wall.png
new file mode 100644
index 0000000..930d786
Binary files /dev/null and b/docs/_static/label/mirror_mirror_on_the_wall.png differ
diff --git a/docs/_static/label/resources/mirror_mirror_on_the_wall.xcf b/docs/_static/label/resources/mirror_mirror_on_the_wall.xcf
new file mode 100644
index 0000000..794cf7b
Binary files /dev/null and b/docs/_static/label/resources/mirror_mirror_on_the_wall.xcf differ
diff --git a/docs/_static/label/resources/the_little_relay_that_could.xcf b/docs/_static/label/resources/the_little_relay_that_could.xcf
new file mode 100644
index 0000000..2589e8d
Binary files /dev/null and b/docs/_static/label/resources/the_little_relay_that_could.xcf differ
diff --git a/docs/_static/label/the_little_relay_that_could.png b/docs/_static/label/the_little_relay_that_could.png
new file mode 100644
index 0000000..8c23539
Binary files /dev/null and b/docs/_static/label/the_little_relay_that_could.png differ
diff --git a/docs/_static/section/tutorial/mirror.png b/docs/_static/section/tutorial/mirror.png
new file mode 100644
index 0000000..69c2938
Binary files /dev/null and b/docs/_static/section/tutorial/mirror.png differ
diff --git a/docs/_static/section/tutorial/train.png b/docs/_static/section/tutorial/train.png
new file mode 100644
index 0000000..625b82e
Binary files /dev/null and b/docs/_static/section/tutorial/train.png differ
diff --git a/docs/contents.rst b/docs/contents.rst
index 6b0311c..390f0a9 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -36,3 +36,6 @@ Contents
    api/util/term
    api/util/tor_tools
 
+   tutorial/the_little_relay_that_could
+   tutorial/mirror_mirror_on_the_wall
+
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
index 0ca3d51..e5afa11 100644
--- a/docs/tutorial.rst
+++ b/docs/tutorial.rst
@@ -1,150 +1,42 @@
 Tutorial
 ========
 
-Getting started with any new library can be rather daunting, so let's 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
----------------------------
-
-Let's 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 let's 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()
+.. Image Sources:
+   
+   * The Little Relay That Could - train.png
+     Source: https://openclipart.org/detail/140185/tren-train-by-antroares
+     Author: Antroares
+     License: Public Domain
+     Alternate: https://openclipart.org/detail/1128/train-roadsign-by-ryanlerch
+   
+   * Mirror Mirror On The Wall - mirror.png
+     Source: https://openclipart.org/detail/152155/mirror-frame-by-gsagri04
+     Author: Unknown (gsagri04?)
+     License: Public Domain
+     Alternate: https://openclipart.org/detail/174179/miroir-rectangulaire-by-defaz36-174179
 
-::
-
-  % 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 let's 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).
+Getting started with any new library can be rather daunting, so let's get our feet wet by jumping straight in with a tutorial...
 
-::
+.. list-table::
+   :widths: 1 10
+   :header-rows: 0
 
-  import sys
-  from stem.descriptor.reader import DescriptorReader
-  from stem.util import str_tools
-  
-  # provides a mapping of observed bandwidth to the relay nicknames
-  def get_bw_to_relay():
-    bw_to_relay = {}
-    
-    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)
-    
-    return bw_to_relay
-  
-  # prints the top fifteen relays
-  
-  bw_to_relay = get_bw_to_relay()
-  count = 1
-  
-  for bw_value in sorted(bw_to_relay.keys(), reverse = True):
-    for nickname in bw_to_relay[bw_value]:
-      print "%i. %s (%s/s)" % (count, nickname, str_tools.get_size_label(bw_value, 2))
-      count += 1
-      
-      if count > 15:
-        sys.exit()
+   * - .. image:: /_static/section/tutorial/train.png
+          :target: tutorial/the_little_relay_that_could.html
 
-::
+     - .. image:: /_static/label/the_little_relay_that_could.png
+          :target: tutorial/the_little_relay_that_could.html
 
-  % python example.py
-  1. herngaard (40.95 MB/s)
-  2. chaoscomputerclub19 (40.43 MB/s)
-  3. chaoscomputerclub18 (40.02 MB/s)
-  4. chaoscomputerclub20 (38.98 MB/s)
-  5. wannabe (38.63 MB/s)
-  6. dorrisdeebrown (38.48 MB/s)
-  7. manning2 (38.20 MB/s)
-  8. chaoscomputerclub21 (36.90 MB/s)
-  9. TorLand1 (36.22 MB/s)
-  10. bolobolo1 (35.93 MB/s)
-  11. manning1 (35.39 MB/s)
-  12. gorz (34.10 MB/s)
-  13. ndnr1 (25.36 MB/s)
-  14. politkovskaja2 (24.93 MB/s)
-  15. wau (24.72 MB/s)
+       "Hello World" for talking with Tor. This will step you through
+       configuring Tor and writing your first script to talk with it.
 
-This can be easily done through the controller too...
+   * - .. image:: /_static/section/tutorial/mirror.png
+          :target: tutorial/mirror_mirror_on_the_wall.html
 
-::
+     - .. image:: /_static/label/mirror_mirror_on_the_wall.png
+          :target: tutorial/mirror_mirror_on_the_wall.html
 
-  def get_bw_to_relay():
-    bw_to_relay = {}
-    
-    with Controller.from_port(control_port = 9051) as controller:
-      controller.authenticate()
-      
-      for desc in controller.get_server_descriptors():
-        if desc.exit_policy.is_exiting_allowed():
-          bw_to_relay.setdefault(desc.observed_bandwidth, []).append(desc.nickname)
-    
-    return bw_to_relay
+       Getting and acting on information about relays in the Tor network. This
+       walks you through Tor descriptors, both where to get them and writing a
+       small script to tell you the fastest Tor exits.
 
diff --git a/docs/tutorial/mirror_mirror_on_the_wall.rst b/docs/tutorial/mirror_mirror_on_the_wall.rst
new file mode 100644
index 0000000..d9a4dd8
--- /dev/null
+++ b/docs/tutorial/mirror_mirror_on_the_wall.rst
@@ -0,0 +1,83 @@
+Mirror Mirror on the Wall
+-------------------------
+
+A script that tells us our contributed bandwidth is neat and all, but now let's 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
+  from stem.util import str_tools
+  
+  # provides a mapping of observed bandwidth to the relay nicknames
+  def get_bw_to_relay():
+    bw_to_relay = {}
+    
+    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)
+    
+    return bw_to_relay
+  
+  # prints the top fifteen relays
+  
+  bw_to_relay = get_bw_to_relay()
+  count = 1
+  
+  for bw_value in sorted(bw_to_relay.keys(), reverse = True):
+    for nickname in bw_to_relay[bw_value]:
+      print "%i. %s (%s/s)" % (count, nickname, str_tools.get_size_label(bw_value, 2))
+      count += 1
+      
+      if count > 15:
+        sys.exit()
+
+::
+
+  % python example.py
+  1. herngaard (40.95 MB/s)
+  2. chaoscomputerclub19 (40.43 MB/s)
+  3. chaoscomputerclub18 (40.02 MB/s)
+  4. chaoscomputerclub20 (38.98 MB/s)
+  5. wannabe (38.63 MB/s)
+  6. dorrisdeebrown (38.48 MB/s)
+  7. manning2 (38.20 MB/s)
+  8. chaoscomputerclub21 (36.90 MB/s)
+  9. TorLand1 (36.22 MB/s)
+  10. bolobolo1 (35.93 MB/s)
+  11. manning1 (35.39 MB/s)
+  12. gorz (34.10 MB/s)
+  13. ndnr1 (25.36 MB/s)
+  14. politkovskaja2 (24.93 MB/s)
+  15. wau (24.72 MB/s)
+
+This can be easily done through the controller too...
+
+::
+
+  def get_bw_to_relay():
+    bw_to_relay = {}
+    
+    with Controller.from_port(control_port = 9051) as controller:
+      controller.authenticate()
+      
+      for desc in controller.get_server_descriptors():
+        if desc.exit_policy.is_exiting_allowed():
+          bw_to_relay.setdefault(desc.observed_bandwidth, []).append(desc.nickname)
+    
+    return bw_to_relay
+
+
diff --git a/docs/tutorial/the_little_relay_that_could.rst b/docs/tutorial/the_little_relay_that_could.rst
new file mode 100644
index 0000000..e3f7675
--- /dev/null
+++ b/docs/tutorial/the_little_relay_that_could.rst
@@ -0,0 +1,56 @@
+The Little Relay that Could
+---------------------------
+
+Let's 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 let's 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.
+



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