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

.azure-pipelines/main.yml

@@ -5,3 +5,4 @@ pr:
 
 jobs:
   - template: templates/jobs/standard-tests-jobs.yml
+

.azure-pipelines/templates/jobs/standard-tests-jobs.yml

@@ -73,3 +73,8 @@ jobs:
       vmImage: $(IMAGE_NAME)
     steps:
       - template: ../steps/tox-steps.yml
+  - job: test_sphinx_builds
+    pool:
+      vmImage: ubuntu-latest
+    steps:
+      - template: ../steps/sphinx-steps.yml

.azure-pipelines/templates/steps/sphinx-steps.yml

@@ -0,0 +1,23 @@
+steps:
+  - bash: |
+      FINAL_STATUS=0
+      declare -a FAILED_BUILDS
+      python3 -m venv .venv
+      source .venv/bin/activate
+      python tools/pipstrap.py
+      for doc_path in */docs
+      do
+        echo ""
+        echo "##[group]Building $doc_path"
+        pip install -q -e $doc_path/..[docs]
+        if ! sphinx-build -W --keep-going -b html $doc_path $doc_path/_build/html; then
+          FINAL_STATUS=1
+          FAILED_BUILDS[${#FAILED_BUILDS[@]}]="${doc_path%/docs}"
+        fi
+        echo "##[endgroup]"
+      done
+      if [[ $FINAL_STATUS -ne 0 ]]; then
+        echo "##[error]The following builds failed: ${FAILED_BUILDS[*]}"
+        exit 1
+      fi
+    displayName: Build Sphinx Documentation

acme/acme/challenges.py

@@ -150,7 +150,7 @@ class KeyAuthorizationChallenge(_TokenChallenge):
     """Challenge based on Key Authorization.
 
     :param response_cls: Subclass of `KeyAuthorizationChallengeResponse`
-        that will be used to generate `response`.
+        that will be used to generate ``response``.
     :param str typ: type of the challenge
     """
     typ = NotImplemented

acme/acme/errors.py

@@ -49,7 +49,7 @@ class MissingNonce(NonceError):
     Replay-Nonce header field in each successful response to a POST it
     provides to a client (...)".
 
-    :ivar requests.Response response: HTTP Response
+    :ivar requests.Response ~.response: HTTP Response
 
     """
     def __init__(self, response, *args, **kwargs):

acme/acme/messages.py

@@ -275,7 +275,7 @@ class Resource(jose.JSONObjectWithFields):
 class ResourceWithURI(Resource):
     """ACME Resource with URI.
 
-    :ivar unicode uri: Location of the resource.
+    :ivar unicode ~.uri: Location of the resource.
 
     """
     uri = jose.Field('uri')  # no ChallengeResource.uri
@@ -627,7 +627,7 @@ class Order(ResourceBody):
     :ivar str finalize: URL to POST to to request issuance once all
         authorizations have "valid" status.
     :ivar datetime.datetime expires: When the order expires.
-    :ivar .Error error: Any error that occurred during finalization, if applicable.
+    :ivar ~.Error error: Any error that occurred during finalization, if applicable.
     """
     identifiers = jose.Field('identifiers', omitempty=True)
     status = jose.Field('status', decoder=Status.from_json,

acme/docs/conf.py

@@ -85,7 +85,10 @@ language = 'en'
 
 # 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/*'
+]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

certbot-dns-cloudflare/docs/conf.py

@@ -111,7 +111,7 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
 # 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 = ['_static']
 
 
 # -- Options for HTMLHelp output ------------------------------------------

certbot-dns-cloudxns/docs/conf.py

@@ -111,7 +111,7 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
 # 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 = ['_static']
 
 
 # -- Options for HTMLHelp output ------------------------------------------

certbot-dns-digitalocean/docs/conf.py

@@ -111,7 +111,7 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
 # 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 = ['_static']
 
 
 # -- Options for HTMLHelp output ------------------------------------------

certbot-dns-dnsimple/docs/conf.py

@@ -111,7 +111,7 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
 # 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 = ['_static']
 
 
 # -- Options for HTMLHelp output ------------------------------------------

certbot-dns-dnsmadeeasy/docs/conf.py

@@ -111,7 +111,7 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
 # 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 = ['_static']
 
 
 # -- Options for HTMLHelp output ------------------------------------------

certbot-dns-gehirn/docs/conf.py

@@ -111,7 +111,7 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
 # 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 = ['_static']
 
 
 # -- Options for HTMLHelp output ------------------------------------------

certbot-dns-google/docs/conf.py

@@ -112,7 +112,7 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
 # 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 = ['_static']
 
 
 # -- Options for HTMLHelp output ------------------------------------------

certbot-dns-linode/docs/conf.py

@@ -111,7 +111,7 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
 # 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 = ['_static']
 
 
 # -- Options for HTMLHelp output ------------------------------------------

certbot-dns-luadns/docs/conf.py

@@ -111,7 +111,7 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
 # 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 = ['_static']
 
 
 # -- Options for HTMLHelp output ------------------------------------------

certbot-dns-nsone/docs/conf.py

@@ -111,7 +111,7 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
 # 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 = ['_static']
 
 
 # -- Options for HTMLHelp output ------------------------------------------

certbot-dns-ovh/docs/conf.py

@@ -111,7 +111,7 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
 # 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 = ['_static']
 
 
 # -- Options for HTMLHelp output ------------------------------------------

certbot-dns-rfc2136/docs/conf.py

@@ -111,7 +111,7 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
 # 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 = ['_static']
 
 
 # -- Options for HTMLHelp output ------------------------------------------

certbot-dns-route53/docs/conf.py

@@ -111,7 +111,7 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
 # 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 = ['_static']
 
 
 # -- Options for HTMLHelp output ------------------------------------------

certbot-dns-route53/setup.py

@@ -36,6 +36,11 @@ elif 'bdist_wheel' in sys.argv[1:]:
 elif sys.version_info < (3,3):
     install_requires.append('mock')
 
+docs_extras = [
+    'Sphinx>=1.0',  # autodoc_member_order = 'bysource', autodoc_default_flags
+    'sphinx_rtd_theme',
+]
+
 setup(
     name='certbot-dns-route53',
     version=version,
@@ -70,6 +75,9 @@ setup(
     include_package_data=True,
     install_requires=install_requires,
     keywords=['certbot', 'route53', 'aws'],
+    extras_require={
+        'docs': docs_extras,
+    },
     entry_points={
         'certbot.plugins': [
             'dns-route53 = certbot_dns_route53._internal.dns_route53:Authenticator',

certbot-dns-sakuracloud/docs/conf.py

@@ -111,7 +111,7 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
 # 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 = ['_static']
 
 
 # -- Options for HTMLHelp output ------------------------------------------

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.