Fix and automatically check for broken links in doc job (#3741)

.azure-pipelines-gh-pages.yml

@@ -28,6 +28,16 @@ jobs:
         parameters:
           cmake_args: ""
 
+      - script: |
+          set -ex
+          python3.8 -m venv env
+          source env/bin/activate
+          pip install wheel
+          pip install -U -r doc/requirements.txt
+          pip install -U -e ./python
+          sphinx-build -b linkcheck doc build/html
+        displayName: Link checks
+
       # Only the main branch builds and publishes the versioned documentation.
       # This is because the configuration of the docs (e.g. theme) will change
       # over time and only the main branch should be source of truth and be

doc/build_apps/auth/jwt.rst

@@ -132,8 +132,7 @@ If an issuer should not be used anymore, then a ``remove_jwt_issuer`` proposal c
 Validating tokens
 -----------------
 
-Validating a token means checking its format, signature, and IdP- and app-specific claims.
-See `tests/js-authentication/src/endpoints.ts <https://github.com/microsoft/CCF/blob/main/tests/js-authentication/src/endpoints.ts>`_ for an example on how to do this in TypeScript.
+Validating a token means checking its format, signature, and IdP- and app-specific claims. See :ccf_repo:`tests/js-authentication/src/endpoints.js` for an example on how to do this in TypeScript.
 
 Token signing keys are stored in the ``public:ccf.gov.jwt.public_signing_keys`` kv map where the key is the key ID and the value the DER-encoded X.509 certificate. The key ID matches the ``kid`` field in the token header and can be used to retrieve the matching certificate for validation.
 

doc/build_apps/build_app.rst

@@ -16,7 +16,7 @@ The :term:`Open Enclave` configuration file (``oe_sign.conf``) should be placed
 
 .. literalinclude:: ../../samples/apps/logging/oe_sign.conf
 
-.. note:: The `Open Enclave documentation <https://github.com/openenclave/openenclave/blob/main/docs/GettingStartedDocs/buildandsign.md#signing-an-SGX-enclave>`_ provides details about the enclave settings in the ``oe_sign.conf`` configuration file.
+.. note:: The `Open Enclave documentation <https://github.com/openenclave/openenclave/blob/master/docs/GettingStartedDocs/buildandsign.md#signing-an-sgx-enclave>`_ provides details about the enclave settings in the ``oe_sign.conf`` configuration file.
 
 Standalone Signing
 ------------------
@@ -53,4 +53,4 @@ It is then possible to inspect the signed enclave library:
 
 For a given application, the ``signature`` field depends on the key used to sign the enclave. See :ref:`governance/common_member_operations:Updating Code Version` for instructions on how members can register new application versions (``mrenclave`` field).
 
-.. note:: The `Open Enclave documentation <https://github.com/openenclave/openenclave/blob/main/docs/GettingStartedDocs/buildandsign.md#signing-an-SGX-enclave>`_. provides further details about how to sign enclave applications using ``oesign``.
+.. note:: The `Open Enclave documentation <https://github.com/openenclave/openenclave/blob/master/docs/GettingStartedDocs/buildandsign.md#signing-an-sgx-enclave>`_. provides further details about how to sign enclave applications using ``oesign``.

doc/build_apps/js_app_ts.rst

@@ -164,7 +164,7 @@ A note on CommonJS modules
 --------------------------
 
 The sample project uses the
-`@rollup/plugin-commonjs <https://github.com/rollup/plugins/tree/main/packages/commonjs>`_
+`@rollup/plugin-commonjs <https://github.com/rollup/plugins/tree/master/packages/commonjs>`_
 package to automatically convert npm packages with CommonJS modules to native JavaScript modules
 so that they can be used in CCF.
 

doc/conf.py

@@ -95,6 +95,15 @@ exclude_patterns = []
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "zenburn"
 
+# Ignore main index file that has clickable images, JS/Doxygen output and
+# github anchors https://github.com/sphinx-doc/sphinx/issues/9016)
+linkcheck_exclude_documents = [r"^index$"]
+linkcheck_ignore = [
+    r"https://github.com/.*#",
+    r"../js/ccf-app.*",
+    r"../doxygen/index.html",
+]
+
 
 # -- Options for HTML output -------------------------------------------------
 

doc/contribute/build_setup.rst

@@ -38,7 +38,7 @@ Visual Studio Code Setup
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you use `Visual Studio Code`_ you can install the `Remote Container`_ extension and use the sample `devcontainer.json`_ config.
-`More details on that process <https://code.visualstudio.com/docs/remote/containers#_quick-start-open-a-public-git-repository-in-an-isolated-container-volume>`_.
+`More details on that process <https://code.visualstudio.com/docs/remote/containers#_quick-start-open-a-git-repository-or-github-pr-in-an-isolated-container-volume>`_.
 
 
 .. _`Visual Studio Code`: https://code.visualstudio.com/

doc/governance/hsm_keys.rst

@@ -5,7 +5,7 @@ This page explains how members' identity certificates and encryption keys stored
 
 .. note::
 
-    It is assumed that CCF members already have access to an existing Azure Key Vault. See `these instructions <https://docs.microsoft.com/en-us/azure/key-vault/secrets/quick-create-portal#create-a-vault>`_ for more details on how to create one. Using the `Azure CLI <https://docs.microsoft.com/en-us/cli/azure/install-azure-cli>`_, it is possible to check the list of available Key Vault instances:
+    It is assumed that CCF members already have access to an existing Azure Key Vault. See `these instructions <https://docs.microsoft.com/en-us/azure/key-vault/general/quick-create-portal#create-a-vault>`_ for more details on how to create one. Using the `Azure CLI <https://docs.microsoft.com/en-us/cli/azure/install-azure-cli>`_, it is possible to check the list of available Key Vault instances:
 
     .. code-block:: bash
 
@@ -16,7 +16,7 @@ This page explains how members' identity certificates and encryption keys stored
 Certificate and Key Generation
 ------------------------------
 
-Members' identity certificates should be generated on the `secp384r1` elliptic curve, using the `az keyvault certificate create <https://docs.microsoft.com/en-us/cli/azure/keyvault/certificate?view=azure-cli-latest#az_keyvault_certificate_create>`_ command, with the following ``identity_cert_policy_example.json`` policy:
+Members' identity certificates should be generated on the `secp384r1` elliptic curve, using the `az keyvault certificate create <https://docs.microsoft.com/en-us/cli/azure/keyvault/certificate?view=azure-cli-latest#az-keyvault-certificate-create>`_ command, with the following ``identity_cert_policy_example.json`` policy:
 
 .. include:: akv_identity_cert_policy.json
     :literal:
@@ -31,7 +31,7 @@ Members' identity certificates should be generated on the `secp384r1` elliptic c
     $ az keyvault key show --vault-name $VAULT_NAME --name $IDENTITY_CERT_NAME
     # Outputs key information, including kid url
 
-Members' encryption keys should be RSA 2048 keys, generated with the `az keyvault key create <https://docs.microsoft.com/en-us/cli/azure/keyvault/key?view=azure-cli-latest#az_keyvault_key_create>`_ command:
+Members' encryption keys should be RSA 2048 keys, generated with the `az keyvault key create <https://docs.microsoft.com/en-us/cli/azure/keyvault/key?view=azure-cli-latest#az-keyvault-key-create>`_ command:
 
 .. code-block:: bash
 
@@ -52,7 +52,7 @@ The identity certificate and public encryption key can be downloaded to a PEM fi
 HTTP Request Signature
 ----------------------
 
-As the Azure CLI (``az keyvault ...``) does not currently support signing/verifying, it is required to use the `corresponding REST API <https://docs.microsoft.com/en-us/rest/api/keyvault/sign/sign>`_ instead. To do so, it is necessary to create a service principal that will be used for authentication:
+As the Azure CLI (``az keyvault ...``) does not currently support signing/verifying, it is required to use the `corresponding REST API <https://docs.microsoft.com/en-us/rest/api/keyvault/keys/sign/sign>`_ instead. To do so, it is necessary to create a service principal that will be used for authentication:
 
 .. code-block:: bash
 

doc/index.rst

@@ -4,29 +4,29 @@ CCF Documentation
 .. panels::
 
     :fa:`info-circle` :doc:`overview/index`
-    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
     .. image:: img/ccf.svg
       :width: 75
       :align: left
-      :target: what_is_ccf.html
+      :target: ./overview/what_is_ccf.html
 
     Get started with the Confidential Consortium Framework and its core concepts.
 
     ---
 
     :fa:`tools` :doc:`build_apps/index`
-    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
     .. image:: img/ts.svg
       :width: 32
-      :target: build_apps/js_app.html
+      :target: ./build_apps/js_app.html
       :alt: TypeScript
       :align: left
 
     .. image:: img/cpp.svg
       :width: 32
-      :target: build_apps/example.html
+      :target: ./build_apps/example.html
       :alt: C++
       :align: left
 
@@ -42,21 +42,21 @@ CCF Documentation
     ---
 
     :fa:`tachometer-alt` :doc:`operations/index`
-    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
     Provision and operate a network of CCF nodes hosting an application.
 
     ---
 
     :fa:`users` :doc:`governance/index`
-    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
     Propose and vote changes to a CCF network, the rules that define it and the application it runs.
 
     ---
 
     :fa:`eye` :doc:`audit/index`
-    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
     Audit a running CCF network and its complete history.
 
@@ -77,7 +77,7 @@ CCF Documentation
     ---
 
     :fa:`flask` :doc:`research/index`
-    ^^^^^^^^^^^^^^^^^^^^^^^^^^
+    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
     CCF-related research papers and technical reports.
 

doc/overview/glossary.rst

@@ -63,7 +63,7 @@ Glossary
     The ring buffer is a data structure that allows communication between the (unprotected) host and the enclave. Data that is written to one side can be read on the other. Only specific types of messages are supported to make sure each package that goes across is read by the right process in the right way.
 
   REST
-    `Representational state transfer <Representational state transfer>`_ is a set of constraints on web APIs, usually implemented over HTTP using JSON as request and response objects exchanged between a requesting client and an implementation server.
+    `Representational state transfer <https://en.wikipedia.org/wiki/Representational_state_transfer>`_ is a set of constraints on web APIs, usually implemented over HTTP using JSON as request and response objects exchanged between a requesting client and an implementation server.
 
   RPC
     `Remote Procedure Call <https://en.wikipedia.org/wiki/Remote_procedure_call>`_ is a way to execute functions in remote machines. CCF uses :term:`REST` host services to allow clients to execute programs inside the :term:`enclave` via the :term:`ring buffer`.