[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[tor-commits] [stem/master] Download links for tutorial examples
commit 5696286d8af3fd5fc1d0fa53cad20cfeb3ffff6c
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
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
::
_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits