commit 5696286d8af3fd5fc1d0fa53cad20cfeb3ffff6c Author: Damian Johnson <atagar@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 ::