[tor-commits] [sbws/maint-1.1] fix: doc: Sphinx warnings when creating documentation

[juga at torproject.org]

commit c931dd014e7fce265da9a46dd48fb9c304c0efeb
Author: Georg Koppen <gk at torproject.org>
Date:   Mon Dec 21 09:30:39 2020 +0000

    fix: doc: Sphinx warnings when creating documentation
    
    This should give us at least a clean html, text, and man build
    experience.
    
    Closes #40036.
---
 AUTHORS.md                   | 3 ++-
 README.md                    | 3 ++-
 docs/source/conf.py          | 2 +-
 docs/source/torflow_aggr.rst | 2 +-
 sbws/lib/relaylist.py        | 5 +++--
 sbws/lib/relayprioritizer.py | 1 +
 sbws/lib/resultdump.py       | 2 +-
 sbws/lib/v3bwfile.py         | 2 +-
 sbws/util/stem.py            | 3 ++-
 9 files changed, 14 insertions(+), 9 deletions(-)

diff --git a/AUTHORS.md b/AUTHORS.md
index 4eaef8f..1e8641e 100644
--- a/AUTHORS.md
+++ b/AUTHORS.md
@@ -1,4 +1,5 @@
-# Authors
+Authors
+=======
 
 The following people have contributed to Simple Bandwidth Scanner.
 Thank you for helping make Tor better.
diff --git a/README.md b/README.md
index 852d02c..fe12cba 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,5 @@
-# Readme
+Readme
+======
 
 [![Build Status](https://travis-ci.org/torproject/sbws.svg?branch=master)](https://travis-ci.org/https://travis-ci.org/torproject/sbws)
 
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 3dc8660..1f33c71 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -97,7 +97,7 @@ html_theme = 'nature'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
diff --git a/docs/source/torflow_aggr.rst b/docs/source/torflow_aggr.rst
index 5b4b3fd..bc9420d 100644
--- a/docs/source/torflow_aggr.rst
+++ b/docs/source/torflow_aggr.rst
@@ -426,4 +426,4 @@ oldest measurements are 5 days old::
 .. _SQLSupport.py: https://gitweb.torproject.org/pytorctl.git/tree/SQLSupport.py#n493
 .. _bandwidth file spec: https://gitweb.torproject.org/torspec.git/tree/bandwidth-file-spec.txt
 .. _aggregate.py: https://gitweb.torproject.org/torflow.git/tree/NetworkScanners/BwAuthority/aggregate.py
-.. _TorCtly.py: https://gitweb.torproject.org/pytorctl.git/tree/TorCtl.py
+.. _TorCtl.py: https://gitweb.torproject.org/pytorctl.git/tree/TorCtl.py
diff --git a/sbws/lib/relaylist.py b/sbws/lib/relaylist.py
index 8a07ce7..bc6b5ce 100644
--- a/sbws/lib/relaylist.py
+++ b/sbws/lib/relaylist.py
@@ -24,6 +24,7 @@ def valid_after_from_network_statuses(network_statuses):
     attribute of a ``stem.descriptor.RouterStatusEntryV3``.
 
     :param list network_statuses:
+
     returns datetime:
     """
     for ns in network_statuses:
@@ -228,7 +229,7 @@ class Relay:
         Increment The number of times that a relay has been queued
         to be measured.
 
-        It is call from :funf:`~sbws.core.scaner.main_loop`.
+        It is call from :func:`~sbws.core.scaner.main_loop`.
         """
         self.relay_recent_measurement_attempt.update()
 
@@ -468,7 +469,7 @@ class RelayList:
         Increment the number of times that any relay has been queued to be
         measured.
 
-        It is call from :funf:`~sbws.core.scaner.main_loop`.
+        It is call from :func:`~sbws.core.scaner.main_loop`.
 
         It is read and stored in a ``state`` file.
         """
diff --git a/sbws/lib/relayprioritizer.py b/sbws/lib/relayprioritizer.py
index ef45391..2d6a488 100644
--- a/sbws/lib/relayprioritizer.py
+++ b/sbws/lib/relayprioritizer.py
@@ -97,6 +97,7 @@ class RelayPrioritizer:
             measurements that did not succed.
         :param bool return_fraction: whether to return only a fraction of the
             relays seen in the network or return all.
+
         return: a generator of the new ordered list of relays to measure next.
 
         """
diff --git a/sbws/lib/resultdump.py b/sbws/lib/resultdump.py
index 9792fde..542837e 100644
--- a/sbws/lib/resultdump.py
+++ b/sbws/lib/resultdump.py
@@ -558,7 +558,7 @@ class ResultErrorSecondRelay(ResultError):
 
     A second suitable relay is a relay that:
     - Has at least equal bandwidth as the relay to measure.
-    - If the relay to measure is not an exit,
+    - If the relay to measure is not an exit, \
       the second relay is an exit without `bad` flag and can exit to port 443.
     - If the relay to measure is an exit, the second relay is not an exit.
 
diff --git a/sbws/lib/v3bwfile.py b/sbws/lib/v3bwfile.py
index 553265b..362c696 100644
--- a/sbws/lib/v3bwfile.py
+++ b/sbws/lib/v3bwfile.py
@@ -625,7 +625,7 @@ class V3BWLine(object):
     :param dict kwargs: extra headers.
 
     .. note:: tech-debt: move node_id and bw to kwargs and just ensure that
-       the required values are in **kwargs
+       the required values are in ``**kwargs``
     """
     def __init__(self, node_id, bw, **kwargs):
         assert isinstance(node_id, str)
diff --git a/sbws/util/stem.py b/sbws/util/stem.py
index ce5253c..5835237 100644
--- a/sbws/util/stem.py
+++ b/sbws/util/stem.py
@@ -118,7 +118,8 @@ def parse_user_torrc_config(torrc, torrc_text):
     """Parse the user configuration torrc text call `extra_lines`
     to a dictionary suitable to use with stem and return a new torrc
     dictionary that merges that dictionary with the existing torrc.
-    Example:
+    Example::
+
         [tor]
         extra_lines =
             Log debug file /tmp/tor-debug.log