[tor-commits] [stem/master] Download links for tutorial examples

atagar at torproject.org atagar at torproject.org
Mon Aug 24 00:27:43 UTC 2020


commit 5696286d8af3fd5fc1d0fa53cad20cfeb3ffff6c
Author: Damian Johnson <atagar at torproject.org>
Date:   Sun Aug 23 17:01:41 2020 -0700

    Download links for tutorial examples
    
    Five years ago we dropped download links from our tutorial examples because
    Debian didn't have Sphinx 1.3...
    
      https://gitweb.torproject.org/stem.git/commit/?id=0541194
      https://trac.torproject.org/projects/tor/ticket/16214
    
    That should now be moot so restoring the links.
    
    This reverts commit 0541194, updated to cover our current tutorials.
---
 docs/change_log.rst                                       | 13 +++++--------
 docs/conf.py                                              |  2 +-
 docs/faq.rst                                              |  2 +-
 docs/tutorials/east_of_the_sun.rst                        |  4 ++++
 docs/tutorials/examples/bandwidth_stats.rst               |  1 +
 docs/tutorials/examples/check_digests.rst                 |  1 +
 docs/tutorials/examples/compare_flags.rst                 |  1 +
 docs/tutorials/examples/download_descriptor.rst           |  1 +
 docs/tutorials/examples/exit_used.rst                     |  1 +
 docs/tutorials/examples/list_circuits.rst                 |  1 +
 docs/tutorials/examples/outdated_relays.rst               |  1 +
 docs/tutorials/examples/persisting_a_consensus.rst        |  2 ++
 docs/tutorials/examples/relay_connections.rst             |  1 +
 .../tutorials/examples/votes_by_bandwidth_authorities.rst |  1 +
 docs/tutorials/mirror_mirror_on_the_wall.rst              | 15 +++++++++++++++
 docs/tutorials/over_the_river.rst                         |  5 +++++
 docs/tutorials/the_little_relay_that_could.rst            |  1 +
 docs/tutorials/to_russia_with_love.rst                    |  4 ++++
 docs/tutorials/tortoise_and_the_hare.rst                  |  4 ++++
 19 files changed, 51 insertions(+), 10 deletions(-)

diff --git a/docs/change_log.rst b/docs/change_log.rst
index abdbb0c9..f30c3a48 100644
--- a/docs/change_log.rst
+++ b/docs/change_log.rst
@@ -68,6 +68,10 @@ The following are only available within Stem's `git repository
 
   * Migrated from distutil to setuptools
 
+ * **Website**
+
+  * Download link for tutorial examples
+
 .. _version_1.8:
 
 Version 1.8 (December 29th, 2019)
@@ -358,15 +362,8 @@ and much more.
 
  * **Website**
 
-  * `Comparison of our descriptor parsing libraries <tutorials/mirror_mirror_on_the_wall.html#are-there-any-other-parsing-libraries>`_
   * Example for `custom path selection for circuits <tutorials/to_russia_with_love.html#custom-path-selection>`_ (:ticket:`archive-8728`)
-  * Example for `persisting ephemeral hidden service keys <tutorials/over_the_river.html#ephemeral-hidden-services>`_
-
- * **Version 1.5.3** (December 5th, 2016) - including tests and site in the
-   release tarball
-
- * **Version 1.5.4** (January 4th, 2017) - drop validation of the order of
-   fields in the tor consensus (:ticket:`archive-21059`)
+  * Download link for tutorial examples (:ticket:`archive-10411`)
 
 .. _version_1.4:
 
diff --git a/docs/conf.py b/docs/conf.py
index b7b21fe4..feaac013 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -51,7 +51,7 @@ sys.path.append(os.path.abspath('.'))
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = '1.1' # required for the sphinx-apidoc command
+needs_sphinx = '1.3' # required for the caption option
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
diff --git a/docs/faq.rst b/docs/faq.rst
index bed7833c..3dd19252 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -640,7 +640,7 @@ example...
 How do I build the site?
 ------------------------
 
-If you have `Sphinx <http://sphinx-doc.org/>`_ version 1.1 or later installed
+If you have `Sphinx <http://sphinx-doc.org/>`_ version 1.3 or later installed
 then building our site is as easy as...
 
 ::
diff --git a/docs/tutorials/east_of_the_sun.rst b/docs/tutorials/east_of_the_sun.rst
index 5b386e0e..3a29443a 100644
--- a/docs/tutorials/east_of_the_sun.rst
+++ b/docs/tutorials/east_of_the_sun.rst
@@ -27,6 +27,7 @@ yourself is easy, but we also provide a module to make it `even easier
 |
 
 .. literalinclude:: /_static/example/words_with.py
+   :caption: `[Download] <../_static/example/words_with.py>`__
    :language: python
 
 .. _multiprocessing:
@@ -46,6 +47,7 @@ that <../api/util/system.html#stem.util.system.DaemonTask>`_.
 **Threaded**
 
 .. literalinclude:: /_static/example/fibonacci_threaded.py
+   :caption: `[Download] <../_static/example/fibonacci_threaded.py>`__
    :language: python
 
 ::
@@ -56,6 +58,7 @@ that <../api/util/system.html#stem.util.system.DaemonTask>`_.
 **Multi-process**
 
 .. literalinclude:: /_static/example/fibonacci_multiprocessing.py
+   :caption: `[Download] <../_static/example/fibonacci_multiprocessing.py>`__
    :language: python
 
 ::
@@ -91,6 +94,7 @@ With that out of the way, how do you look up this information? Below is a
 simple script that dumps Tor's present connections.
 
 .. literalinclude:: /_static/example/utilities.py
+   :caption: `[Download] <../_static/example/utilities.py>`__
    :language: python
 
 ::
diff --git a/docs/tutorials/examples/bandwidth_stats.rst b/docs/tutorials/examples/bandwidth_stats.rst
index 3cfddfea..ae0d782b 100644
--- a/docs/tutorials/examples/bandwidth_stats.rst
+++ b/docs/tutorials/examples/bandwidth_stats.rst
@@ -14,6 +14,7 @@ called **bandwidth authorities**. See our `bandwidth file specification
 details. Statistics are publicly available and generated each hour...
 
 .. literalinclude:: /_static/example/bandwidth_stats.py
+   :caption: `[Download] <../_static/example/bandwidth_stats.py>`__
    :language: python
 
 ::
diff --git a/docs/tutorials/examples/check_digests.rst b/docs/tutorials/examples/check_digests.rst
index dc2f0ee8..8ff1aa67 100644
--- a/docs/tutorials/examples/check_digests.rst
+++ b/docs/tutorials/examples/check_digests.rst
@@ -25,6 +25,7 @@ and `consensus documents
 For instance, to validate an extrainfo descriptor...
 
 .. literalinclude:: /_static/example/check_digests.py
+   :caption: `[Download] <../_static/example/check_digests.py>`__
    :language: python
 
 ::
diff --git a/docs/tutorials/examples/compare_flags.rst b/docs/tutorials/examples/compare_flags.rst
index c6614931..3ea61434 100644
--- a/docs/tutorials/examples/compare_flags.rst
+++ b/docs/tutorials/examples/compare_flags.rst
@@ -8,6 +8,7 @@ Compares the votes of two directory authorities, in this case moria1 and
 maatuska, with a special interest in the 'Running' flag.
 
 .. literalinclude:: /_static/example/compare_flags.py
+   :caption: `[Download] <../../_static/example/compare_flags.py>`__
    :language: python
 
 ::
diff --git a/docs/tutorials/examples/download_descriptor.rst b/docs/tutorials/examples/download_descriptor.rst
index 615eef7d..5c53bc6e 100644
--- a/docs/tutorials/examples/download_descriptor.rst
+++ b/docs/tutorials/examples/download_descriptor.rst
@@ -11,6 +11,7 @@ with http as well from a `DirPort
 <https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt>`_.
 
 .. literalinclude:: /_static/example/download_descriptor.py
+   :caption: `[Download] <../_static/example/download_descriptor.py>`__
    :language: python
 
 ::
diff --git a/docs/tutorials/examples/exit_used.rst b/docs/tutorials/examples/exit_used.rst
index 24a3d7d3..095cd3c2 100644
--- a/docs/tutorials/examples/exit_used.rst
+++ b/docs/tutorials/examples/exit_used.rst
@@ -12,6 +12,7 @@ Here's a simple script that prints information about the exits used to service
 the requests going through Tor...
 
 .. literalinclude:: /_static/example/exit_used.py
+   :caption: `[Download] <../../_static/example/exit_used.py>`__
    :language: python
 
 Now if you make a request over Tor...
diff --git a/docs/tutorials/examples/list_circuits.rst b/docs/tutorials/examples/list_circuits.rst
index d856e314..298089be 100644
--- a/docs/tutorials/examples/list_circuits.rst
+++ b/docs/tutorials/examples/list_circuits.rst
@@ -8,6 +8,7 @@ Tor creates new circuits and tears down old ones on your behalf, so how can you
 get information about circuits Tor currently has available?
 
 .. literalinclude:: /_static/example/list_circuits.py
+   :caption: `[Download] <../../_static/example/list_circuits.py>`__
    :language: python
 
 ::
diff --git a/docs/tutorials/examples/outdated_relays.rst b/docs/tutorials/examples/outdated_relays.rst
index e7b37318..464054a7 100644
--- a/docs/tutorials/examples/outdated_relays.rst
+++ b/docs/tutorials/examples/outdated_relays.rst
@@ -9,6 +9,7 @@ support for old ones. Below is the script we used on :ticket:`tor-9476` to
 reach out to relay operators that needed to upgrade.
 
 .. literalinclude:: /_static/example/outdated_relays.py
+   :caption: `[Download] <../../_static/example/outdated_relays.py>`__
    :language: python
 
 ::
diff --git a/docs/tutorials/examples/persisting_a_consensus.rst b/docs/tutorials/examples/persisting_a_consensus.rst
index facd1814..6e51fe7d 100644
--- a/docs/tutorials/examples/persisting_a_consensus.rst
+++ b/docs/tutorials/examples/persisting_a_consensus.rst
@@ -31,6 +31,7 @@ So how do we get it? Just tell Stem that's what you want. The
 consensus. For example, to write the consensus simply do the following...
 
 .. literalinclude:: /_static/example/persisting_a_consensus.py
+   :caption: `[Download] <../../_static/example/persisting_a_consensus.py>`__
    :language: python
 
 Our *consensus* here is the current
@@ -51,4 +52,5 @@ Our *consensus* here is the current
 You can then read it back with :func:`~stem.descriptor.__init__.parse_file`...
 
 .. literalinclude:: /_static/example/persisting_a_consensus_with_parse_file.py
+   :caption: `[Download] <../../_static/example/persisting_a_consensus_with_parse_file.py>`__
    :language: python
diff --git a/docs/tutorials/examples/relay_connections.rst b/docs/tutorials/examples/relay_connections.rst
index c389f9aa..8c889e6d 100644
--- a/docs/tutorials/examples/relay_connections.rst
+++ b/docs/tutorials/examples/relay_connections.rst
@@ -17,6 +17,7 @@ connections. Couple important notes...
     That said, a general overview like this should be fine.
 
 .. literalinclude:: /_static/example/relay_connections.py
+   :caption: `[Download] <../_static/example/relay_connections.py>`__
    :language: python
 
 ::
diff --git a/docs/tutorials/examples/votes_by_bandwidth_authorities.rst b/docs/tutorials/examples/votes_by_bandwidth_authorities.rst
index cea52e2a..df78ca2a 100644
--- a/docs/tutorials/examples/votes_by_bandwidth_authorities.rst
+++ b/docs/tutorials/examples/votes_by_bandwidth_authorities.rst
@@ -17,6 +17,7 @@ Bandwidth authorities include their measurements in their votes. The following
 gets their current votes then prints how many relays it had a measurement for.
 
 .. literalinclude:: /_static/example/votes_by_bandwidth_authorities.py
+   :caption: `[Download] <../../_static/example/votes_by_bandwidth_authorities.py>`__
    :language: python
 
 ::
diff --git a/docs/tutorials/mirror_mirror_on_the_wall.rst b/docs/tutorials/mirror_mirror_on_the_wall.rst
index 8d72760a..80ae1104 100644
--- a/docs/tutorials/mirror_mirror_on_the_wall.rst
+++ b/docs/tutorials/mirror_mirror_on_the_wall.rst
@@ -76,6 +76,7 @@ which can both be downloaded from using Stem's `stem.descriptor.remote
 easy as...
 
 .. literalinclude:: /_static/example/current_descriptors.py
+   :caption: `[Download] <../_static/example/current_descriptors.py>`__
    :language: python
 
 **Please remember that Tor is a shared resource!** If you're going to
@@ -87,6 +88,7 @@ contribute much load please consider `running a relay
 downloaded from by specifying it as the endpoint... 
 
 .. literalinclude:: /_static/example/descriptor_from_orport.py
+   :caption: `[Download] <../_static/example/descriptor_from_orport.py>`__
    :language: python
 
 **DirPorts** by contrast are simpler and specially designed to offer descriptor
@@ -123,11 +125,13 @@ at a prior point in time this is the place to go!
 With CollecTor you can either read descriptors directly...
 
 .. literalinclude:: /_static/example/collector_reading.py
+   :caption: `[Download] <../_static/example/collector_reading.py>`__
    :language: python
 
 ... or download the descriptors to disk and read them later.
 
 .. literalinclude:: /_static/example/collector_caching.py
+   :caption: `[Download] <../_static/example/collector_caching.py>`__
    :language: python
 
 .. _can-i-get-descriptors-from-the-tor-process:
@@ -179,11 +183,13 @@ Now that Tor is happy chugging along, up-to-date descriptors are available
 through Tor's control socket...
 
 .. literalinclude:: /_static/example/descriptor_from_tor_control_socket.py
+   :caption: `[Download] <../_static/example/descriptor_from_tor_control_socket.py>`__
    :language: python
 
 ... or by reading directly from Tor's data directory...
 
 .. literalinclude:: /_static/example/descriptor_from_tor_data_directory.py
+   :caption: `[Download] <../_static/example/descriptor_from_tor_data_directory.py>`__
    :language: python
 
 .. _can-i-create-descriptors:
@@ -197,6 +203,7 @@ for test data. To do so simply use the
 :class:`~stem.descriptor.__init__.Descriptor` subclasses...
 
 .. literalinclude:: /_static/example/create_descriptor.py
+   :caption: `[Download] <../_static/example/create_descriptor.py>`__
    :language: python
 
 Unspecified mandatory fields are filled with mock data. You can also use
@@ -204,6 +211,7 @@ Unspecified mandatory fields are filled with mock data. You can also use
 descriptor...
 
 .. literalinclude:: /_static/example/create_descriptor_content.py
+   :caption: `[Download] <../_static/example/create_descriptor_content.py>`__
    :language: python
 
 ::
@@ -247,6 +255,7 @@ Validating is as simple as including **validate = True** in any method that
 provides descriptors...
 
 .. literalinclude:: /_static/example/validate_descriptor_content.py
+   :caption: `[Download] <../_static/example/validate_descriptor_content.py>`__
    :language: python
 
 .. _saving-and-loading-descriptors:
@@ -259,6 +268,7 @@ Tor descriptors are just plaintext documents. As such, if you'd rather not use
 descriptor by simply writing it to disk, then reading it back later.
 
 .. literalinclude:: /_static/example/saving_and_loading_descriptors.py
+   :caption: `[Download] <../_static/example/saving_and_loading_descriptors.py>`__
    :language: python
 
 Our *server_descriptors* here is a list of
@@ -281,6 +291,7 @@ We can then read it back with :func:`~stem.descriptor.__init__.parse_file`
 by telling it the type of descriptors we're reading...
 
 .. literalinclude:: /_static/example/read_with_parse_file.py
+   :caption: `[Download] <../_static/example/read_with_parse_file.py>`__
    :language: python
 
 For an example of doing this with a consensus document `see here
@@ -303,6 +314,7 @@ could use any of the methods above, but for this example we'll use
 `stem.descriptor.remote <../api/descriptor/remote.html>`_...
 
 .. literalinclude:: /_static/example/tor_descriptors.py
+   :caption: `[Download] <../_static/example/tor_descriptors.py>`__
    :language: python
 
 ::
@@ -395,6 +407,7 @@ Stem Example
 * `Stem Benchmark Script <../.../../_static/example/benchmark_stem.py>`_
 
 .. literalinclude:: /_static/example/benchmark_server_descriptor_stem.py
+   :caption: `[Download] <../_static/example/benchmark_server_descriptor_stem.py>`__
    :language: python
 
 Metrics-lib Example
@@ -403,6 +416,7 @@ Metrics-lib Example
 * `Metrics-lib Benchmark Script <../.../../_static/example/benchmark_metrics_lib.java>`_
 
 .. literalinclude:: /_static/example/benchmark_server_descriptor_metrics_lib.java
+   :caption: `[Download] <../_static/example/benchmark_server_descriptor_metrics_lib.py>`__
    :language: java
 
 Zoossh Example
@@ -411,4 +425,5 @@ Zoossh Example
 * `Zoossh Benchmark Script <../.../../_static/example/benchmark_zoossh.go>`_
 
 .. literalinclude:: /_static/example/benchmark_server_descriptor_zoossh.go
+   :caption: `[Download] <../_static/example/benchmark_server_descriptor_zoossh.py>`__
    :language: go
diff --git a/docs/tutorials/over_the_river.rst b/docs/tutorials/over_the_river.rst
index ff8c7feb..294c7fec 100644
--- a/docs/tutorials/over_the_river.rst
+++ b/docs/tutorials/over_the_river.rst
@@ -52,6 +52,7 @@ But with that out of the way lets take a look at a simple `Flask
 <https://jordan-wright.github.io/blog/2014/10/06/creating-tor-hidden-services-with-python/>`_...
 
 .. literalinclude:: /_static/example/running_hidden_service.py
+   :caption: `[Download] <../_static/example/running_hidden_service.py>`__
    :language: python
 
 Now if we run this...
@@ -125,6 +126,7 @@ Stem provides three methods to work with ephemeral hidden services...
 For example, with a ephemeral service our earlier example becomes as simple as...
 
 .. literalinclude:: /_static/example/ephemeral_hidden_services.py
+   :caption: `[Download] <../_static/example/ephemeral_hidden_services.py>`__
    :language: python
 
 Ephemeral hidden services do not touch disk, and as such are easier to work
@@ -132,6 +134,7 @@ with but require you to persist your service's private key yourself if you want
 to reuse a '.onion' address...
 
 .. literalinclude:: /_static/example/resuming_ephemeral_hidden_service.py
+   :caption: `[Download] <../_static/example/resuming_ephemeral_hidden_service.py>`__
    :language: python
 
 .. _hidden-service-descriptors:
@@ -145,6 +148,7 @@ connections. Hidden service descriptors are available from the tor process via
 its :func:`~stem.control.Controller.get_hidden_service_descriptor` method...
 
 .. literalinclude:: /_static/example/get_hidden_service_descriptor.py
+   :caption: `[Download] <../_static/example/get_hidden_service_descriptor.py>`__
    :language: python
 
 ::
@@ -175,6 +179,7 @@ descriptor's
 method.
 
 .. literalinclude:: /_static/example/introduction_points.py
+   :caption: `[Download] <../_static/example/introduction_points.py>`__
    :language: python
 
 ::
diff --git a/docs/tutorials/the_little_relay_that_could.rst b/docs/tutorials/the_little_relay_that_could.rst
index 34bfe9e0..27785419 100644
--- a/docs/tutorials/the_little_relay_that_could.rst
+++ b/docs/tutorials/the_little_relay_that_could.rst
@@ -48,6 +48,7 @@ unfamiliar with the '**with**' keyword then see `here
 <../faq.html#what-is-that-with-keyword-i-keep-seeing-in-the-tutorials>`_...
 
 .. literalinclude:: /_static/example/hello_world.py
+   :caption: `[Download] <../_static/example/hello_world.py>`_
    :language: python
 
 ::
diff --git a/docs/tutorials/to_russia_with_love.rst b/docs/tutorials/to_russia_with_love.rst
index fed3902e..fc1b4d2c 100644
--- a/docs/tutorials/to_russia_with_love.rst
+++ b/docs/tutorials/to_russia_with_love.rst
@@ -52,6 +52,7 @@ improve this example then please `let me know
 <https://www.atagar.com/contact/>`_!
 
 .. literalinclude:: /_static/example/client_usage_using_pycurl.py
+   :caption: `[Download] <../_static/example/client_usage_using_pycurl.py>`__
    :language: python
 
 .. image:: /_static/locale_selection_output.png
@@ -68,6 +69,7 @@ control port. To use this approach simply replace the query() function above
 with...
 
 .. literalinclude::  /_static/example/client_usage_using_socksipy.py
+   :caption: `[Download] <../_static/example/client_usage_using_socksipy.py>`__
    :language: python
 
 .. _reading-twitter:
@@ -82,6 +84,7 @@ authentication `see their instructions
 <https://dev.twitter.com/oauth/overview/application-owner-access-tokens>`_...
 
 .. literalinclude:: /_static/example/reading_twitter.py
+   :caption: `[Download] <../_static/example/reading_twitter.py>`__
    :language: python
 
 .. image:: /_static/twitter_output.png
@@ -112,6 +115,7 @@ reachability and speed. **Naturally doing this causes quite a bit of load so
 please be careful not to leave this running!**
 
 .. literalinclude:: /_static/example/custom_path_selection.py
+   :caption: `[Download] <../_static/example/custom_path_selection.py>`__
    :language: python
 
 ::
diff --git a/docs/tutorials/tortoise_and_the_hare.rst b/docs/tutorials/tortoise_and_the_hare.rst
index 8d4f6268..7e56ec99 100644
--- a/docs/tutorials/tortoise_and_the_hare.rst
+++ b/docs/tutorials/tortoise_and_the_hare.rst
@@ -29,6 +29,7 @@ are events that Tor emits each second saying the number of bytes downloaded and
 uploaded.
 
 .. literalinclude:: /_static/example/event_listening.py
+   :caption: `[Download] <../_static/example/event_listening.py>`__
    :emphasize-lines: 53-55,62-67
    :language: python
 
@@ -41,6 +42,7 @@ can make troubleshooting your code confusing. For example, exceptions have
 nowhere to propagate...
 
 .. literalinclude:: /_static/example/broken_listener.py
+   :caption: `[Download] <../_static/example/broken_listener.py>`__
    :language: python
 
 ::
@@ -54,6 +56,7 @@ nowhere to propagate...
 fall behind. This can result in a memory leak for long running processes...
 
 .. literalinclude:: /_static/example/slow_listener.py
+   :caption: `[Download] <../_static/example/slow_listener.py>`__
    :language: python
 
 ::
@@ -67,6 +70,7 @@ Avoid performing heavy business logic directly within listeners. For example, a
 producer/consumer pattern sidesteps these issues...
 
 .. literalinclude:: /_static/example/queue_listener.py
+   :caption: `[Download] <../_static/example/queue_listener.py>`__
    :language: python
 
 ::



More information about the tor-commits mailing list