Automatically Catch Sphinx Errors (#8530)

* clean up some Sphinx warnings

* first attempt at a doc-test pipeline job

* fix formatting

* fix test name

* set env for bash

* try bash vs script

* maybe it didn't like me setting 'PATH'...derp

* drop use of venv

* sphinx-build isn't a py script

* try activating venv

* docs: remove unused html_static tags

* clean up final sphinx build errors for certbot

* clean up final sphinx build errors for acme

* better names for docs pipeline

* fix spelling

* add docs_extras to setup.py

* remove temp doc-testing pipeline; add template to main.yml

* rearrange pipeline execution; run sphinx builds in one job

* add documentation note to compat.os

* add uninstall.rst as a sub-toctree to avoid build error

certbot/certbot/achallenges.py

@@ -33,7 +33,7 @@ class AnnotatedChallenge(jose.ImmutableMap):
     Wraps around server provided challenge and annotates with data
     useful for the client.
 
-    :ivar challb: Wrapped `~.ChallengeBody`.
+    :ivar ~.challb: Wrapped `~.ChallengeBody`.
 
     """
     __slots__ = ('challb',)

certbot/certbot/compat/os.py

@@ -7,6 +7,10 @@ This module has the same API as the os module in the Python standard library
 except for the functions defined below.
 
 """
+
+# NOTE: If adding a new documented function to compat.os, ensure that it is added to the
+#       ':members:' list in certbot/docs/api/certbot.compat.os.rst.
+
 # isort:skip_file
 # pylint: disable=function-redefined
 from __future__ import absolute_import

certbot/certbot/crypto_util.py

@@ -291,7 +291,7 @@ def verify_signed_payload(public_key, signature, payload, signature_hash_algorit
     :param RSAPublicKey/EllipticCurvePublicKey public_key: the public_key to check signature
     :param bytes signature: the signature bytes
     :param bytes payload: the payload bytes
-    :param cryptography.hazmat.primitives.hashes.HashAlgorithm
+    :param cryptography.hazmat.primitives.hashes.HashAlgorithm \
            signature_hash_algorithm: algorithm used to hash the payload
 
     :raises InvalidSignature: If signature verification fails.

certbot/certbot/plugins/util.py

@@ -10,9 +10,11 @@ logger = logging.getLogger(__name__)
 
 def get_prefixes(path):
     """Retrieves all possible path prefixes of a path, in descending order
-    of length. For instance,
-        (linux) /a/b/c returns ['/a/b/c', '/a/b', '/a', '/']
-        (windows) C:\\a\\b\\c returns ['C:\\a\\b\\c', 'C:\\a\\b', 'C:\\a', 'C:']
+    of length. For instance:
+
+      * (Linux) `/a/b/c` returns `['/a/b/c', '/a/b', '/a', '/']`
+      * (Windows) `C:\\a\\b\\c` returns `['C:\\a\\b\\c', 'C:\\a\\b', 'C:\\a', 'C:']`
+
     :param str path: the path to break into prefixes
 
     :returns: all possible path prefixes of given path in descending order

certbot/docs/api/certbot.compat.os.rst

@@ -2,6 +2,4 @@ certbot.compat.os module
 ========================
 
 .. automodule:: certbot.compat.os
-    :members:
-    :undoc-members:
-    :show-inheritance:
+    :members: chmod, umask, chown, open, mkdir, makedirs, rename, replace, access, stat, fstat

certbot/docs/conf.py

@@ -95,7 +95,12 @@ language = None
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = [
+    '_build',
+    'man',
+    'challenges.rst',
+    'ciphers.rst'
+]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

certbot/docs/install.rst

@@ -240,6 +240,11 @@ look at the :doc:`packaging`.
 
 Certbot-Auto
 ------------
+.. toctree::
+   :hidden:
+
+   uninstall
+
 
 We used to have a shell script named ``certbot-auto`` to help people install
 Certbot on UNIX operating systems, however, this script is no longer supported.