diff --git a/.azure-pipelines/main.yml b/.azure-pipelines/main.yml index 1975d36db..cae4f799c 100644 --- a/.azure-pipelines/main.yml +++ b/.azure-pipelines/main.yml @@ -5,3 +5,4 @@ pr: jobs: - template: templates/jobs/standard-tests-jobs.yml + diff --git a/.azure-pipelines/templates/jobs/standard-tests-jobs.yml b/.azure-pipelines/templates/jobs/standard-tests-jobs.yml index 957a4c0b4..2edd0c493 100644 --- a/.azure-pipelines/templates/jobs/standard-tests-jobs.yml +++ b/.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 diff --git a/.azure-pipelines/templates/steps/sphinx-steps.yml b/.azure-pipelines/templates/steps/sphinx-steps.yml new file mode 100644 index 000000000..23c258bbc --- /dev/null +++ b/.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 diff --git a/acme/acme/challenges.py b/acme/acme/challenges.py index b9c6b7eb2..376e9a382 100644 --- a/acme/acme/challenges.py +++ b/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 diff --git a/acme/acme/errors.py b/acme/acme/errors.py index 806657940..5ca5a4fa2 100644 --- a/acme/acme/errors.py +++ b/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): diff --git a/acme/acme/messages.py b/acme/acme/messages.py index 6325ed57f..3a505843d 100644 --- a/acme/acme/messages.py +++ b/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, diff --git a/acme/docs/conf.py b/acme/docs/conf.py index d3e7be371..9d3c4d05c 100644 --- a/acme/docs/conf.py +++ b/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. diff --git a/certbot-dns-cloudflare/docs/conf.py b/certbot-dns-cloudflare/docs/conf.py index 21c1d9b72..b80bdbc97 100644 --- a/certbot-dns-cloudflare/docs/conf.py +++ b/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 ------------------------------------------ diff --git a/certbot-dns-cloudxns/docs/conf.py b/certbot-dns-cloudxns/docs/conf.py index de6f554da..5a350b1b1 100644 --- a/certbot-dns-cloudxns/docs/conf.py +++ b/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 ------------------------------------------ diff --git a/certbot-dns-digitalocean/docs/conf.py b/certbot-dns-digitalocean/docs/conf.py index ab653a2b0..5951e3f98 100644 --- a/certbot-dns-digitalocean/docs/conf.py +++ b/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 ------------------------------------------ diff --git a/certbot-dns-dnsimple/docs/conf.py b/certbot-dns-dnsimple/docs/conf.py index 4c6e6b52e..7f88e6387 100644 --- a/certbot-dns-dnsimple/docs/conf.py +++ b/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 ------------------------------------------ diff --git a/certbot-dns-dnsmadeeasy/docs/conf.py b/certbot-dns-dnsmadeeasy/docs/conf.py index 1dfc1bd89..efe2f36f4 100644 --- a/certbot-dns-dnsmadeeasy/docs/conf.py +++ b/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 ------------------------------------------ diff --git a/certbot-dns-gehirn/docs/conf.py b/certbot-dns-gehirn/docs/conf.py index 75e3705dd..2cc968fe0 100644 --- a/certbot-dns-gehirn/docs/conf.py +++ b/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 ------------------------------------------ diff --git a/certbot-dns-google/docs/conf.py b/certbot-dns-google/docs/conf.py index 8c4a800f7..06bb99f46 100644 --- a/certbot-dns-google/docs/conf.py +++ b/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 ------------------------------------------ diff --git a/certbot-dns-linode/docs/conf.py b/certbot-dns-linode/docs/conf.py index 6305b694c..c916b5097 100644 --- a/certbot-dns-linode/docs/conf.py +++ b/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 ------------------------------------------ diff --git a/certbot-dns-luadns/docs/conf.py b/certbot-dns-luadns/docs/conf.py index 6a11ce7aa..5790a85a7 100644 --- a/certbot-dns-luadns/docs/conf.py +++ b/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 ------------------------------------------ diff --git a/certbot-dns-nsone/docs/conf.py b/certbot-dns-nsone/docs/conf.py index 7e66a0613..4bc13fe2b 100644 --- a/certbot-dns-nsone/docs/conf.py +++ b/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 ------------------------------------------ diff --git a/certbot-dns-ovh/docs/conf.py b/certbot-dns-ovh/docs/conf.py index c8a1575c4..18ebccaac 100644 --- a/certbot-dns-ovh/docs/conf.py +++ b/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 ------------------------------------------ diff --git a/certbot-dns-rfc2136/docs/conf.py b/certbot-dns-rfc2136/docs/conf.py index bc0e9c845..782f494f1 100644 --- a/certbot-dns-rfc2136/docs/conf.py +++ b/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 ------------------------------------------ diff --git a/certbot-dns-route53/docs/conf.py b/certbot-dns-route53/docs/conf.py index f9c5fdf74..bb7808d66 100644 --- a/certbot-dns-route53/docs/conf.py +++ b/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 ------------------------------------------ diff --git a/certbot-dns-route53/setup.py b/certbot-dns-route53/setup.py index 33fd4e2b2..fea63db88 100644 --- a/certbot-dns-route53/setup.py +++ b/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', diff --git a/certbot-dns-sakuracloud/docs/conf.py b/certbot-dns-sakuracloud/docs/conf.py index 9d6d3c871..b84b97e1d 100644 --- a/certbot-dns-sakuracloud/docs/conf.py +++ b/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 ------------------------------------------ diff --git a/certbot/certbot/achallenges.py b/certbot/certbot/achallenges.py index 70588683d..7171c271c 100644 --- a/certbot/certbot/achallenges.py +++ b/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',) diff --git a/certbot/certbot/compat/os.py b/certbot/certbot/compat/os.py index ed1311c67..2f0899bd7 100644 --- a/certbot/certbot/compat/os.py +++ b/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 diff --git a/certbot/certbot/crypto_util.py b/certbot/certbot/crypto_util.py index e0f85c1cd..256454122 100644 --- a/certbot/certbot/crypto_util.py +++ b/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. diff --git a/certbot/certbot/plugins/util.py b/certbot/certbot/plugins/util.py index 87eb45fe9..04a741da6 100644 --- a/certbot/certbot/plugins/util.py +++ b/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 diff --git a/certbot/docs/api/certbot.compat.os.rst b/certbot/docs/api/certbot.compat.os.rst index 3a4c9fe47..c46cee668 100644 --- a/certbot/docs/api/certbot.compat.os.rst +++ b/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 diff --git a/certbot/docs/conf.py b/certbot/docs/conf.py index dbd4067d5..52820b69d 100644 --- a/certbot/docs/conf.py +++ b/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. diff --git a/certbot/docs/install.rst b/certbot/docs/install.rst index c2d79dc33..6a37cd2b4 100644 --- a/certbot/docs/install.rst +++ b/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.