[tor-commits] [stem/master] Test that all examples are referenced

[atagar at torproject.org]

commit ef7416255976b2885733c170a6bde0263a239254
Author: Damian Johnson <atagar at torproject.org>
Date:   Tue Sep 29 16:48:37 2020 -0700

    Test that all examples are referenced
    
    Our unused load_test.py makes it clear that we should check that all our
    examples are cited by the website. I can see myself making that mistake again.
---
 docs/tutorials/to_russia_with_love.rst |  2 +-
 stem/manual.py                         |  2 +-
 test/unit/examples.py                  | 35 ++++++++++++++++++++++++++++++++--
 3 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/docs/tutorials/to_russia_with_love.rst b/docs/tutorials/to_russia_with_love.rst
index fc1b4d2c..af94185a 100644
--- a/docs/tutorials/to_russia_with_love.rst
+++ b/docs/tutorials/to_russia_with_love.rst
@@ -68,7 +68,7 @@ connections through Tor, so this'll break our ability to connect to Tor's
 control port. To use this approach simply replace the query() function above
 with...
 
-.. literalinclude::  /_static/example/client_usage_using_socksipy.py
+.. literalinclude:: /_static/example/client_usage_using_socksipy.py
    :caption: `[Download] <../_static/example/client_usage_using_socksipy.py>`__
    :language: python
 
diff --git a/stem/manual.py b/stem/manual.py
index dbde9827..e7658317 100644
--- a/stem/manual.py
+++ b/stem/manual.py
@@ -21,7 +21,7 @@ Manual information includes arguments, signals, and probably most usefully the
 torrc configuration options. For example, say we want a little script that told
 us what our torrc options do...
 
-.. literalinclude::  /_static/example/manual_config_options.py
+.. literalinclude:: /_static/example/manual_config_options.py
    :language: python
 
 |
diff --git a/test/unit/examples.py b/test/unit/examples.py
index 094322e6..12ffb60c 100644
--- a/test/unit/examples.py
+++ b/test/unit/examples.py
@@ -7,6 +7,7 @@ import binascii
 import functools
 import io
 import os
+import re
 import sys
 import unittest
 
@@ -231,13 +232,13 @@ class TestExamples(unittest.TestCase):
 
     stem.descriptor.remote.SINGLETON_DOWNLOADER = None
 
-  def test_runs_everything(self):
+  def test_everything_is_tested(self):
     """
     Ensure we have tests for all our examples.
     """
 
     all_examples = set([os.path.basename(path)[:-3] for path in stem.util.system.files_with_suffix(EXAMPLE_DIR, '.py')])
-    tested_examples = set([method[5:] for method in dir(self) if method.startswith('test_') and method != 'test_runs_everything'])
+    tested_examples = set([method[5:] for method in dir(self) if method.startswith('test_') and not method.startswith('test_everything_')])
 
     extra = sorted(tested_examples.difference(all_examples))
     missing = sorted(all_examples.difference(tested_examples).difference(UNTESTED))
@@ -248,6 +249,36 @@ class TestExamples(unittest.TestCase):
     if missing:
       self.fail("Changed our examples directory? The following are untested: %s" % ', '.join(missing))
 
+  def test_everything_is_referenced(self):
+    """
+    Ensure that all our examples are referenced our website. Otherwise they're
+    dead code.
+    """
+
+    all_examples = set([os.path.basename(path)[:-3] for path in stem.util.system.files_with_suffix(EXAMPLE_DIR, '.py')])
+
+    include_regex = re.compile('.. literalinclude:: /_static/example/(\\S*).py')
+    referenced_examples = set()
+
+    for path in stem.util.system.files_with_suffix(os.path.join(test.STEM_BASE, 'docs'), '.rst'):
+      with open(path) as example_file:
+        referenced_examples.update(include_regex.findall(example_file.read()))
+
+    for path in stem.util.system.files_with_suffix(os.path.join(test.STEM_BASE, 'stem'), '.py'):
+      with open(path) as source_file:
+        referenced_examples.update(include_regex.findall(source_file.read()))
+
+    extra = sorted(referenced_examples.difference(all_examples))
+    missing = sorted(all_examples.difference(referenced_examples))
+
+    missing.remove('benchmark_stem')  # expanded copy of benchmark_server_descriptor_stem.py
+
+    if extra:
+      self.fail("Changed our documentation? We reference the following examples which are not present: %s" % ', '.join(extra))
+
+    if missing:
+      self.fail("Changed our documntation? The following examples are unreferenced: %s" % ', '.join(missing))
+
   @patch('stem.descriptor.remote.get_bandwidth_file')
   @patch('sys.stdout', new_callable = io.StringIO)
   def test_bandwidth_stats(self, stdout_mock, get_bandwidth_file_mock):