Fix warnings in docs build (#6347)

Co-authored-by: Amaury Chamayou <[email protected]>

doc/audit/builtin_maps.rst

@@ -382,7 +382,7 @@ JWT signing key to Issuer mapping, used until 5.0.
 **Value** JWT issuer URL, represented as a string.
 
 ``jwt.public_signing_keys_metadata``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 JWT signing keys.
 

doc/build_apps/api.rst

@@ -72,7 +72,7 @@ Policies
 .. doxygenvariable:: ccf::jwt_auth_policy
    :project: CCF
 
-.. doxygenvariable:: ccf::TypedUserCOSESign1AuthnPolicy
+.. doxygenclass:: ccf::TypedUserCOSESign1AuthnPolicy
    :project: CCF
 
 Identities

doc/build_apps/auth/jwt.rst

@@ -186,4 +186,4 @@ CCF tracks JWT key auto-refresh attempts and successes.
 This can be used to identify errors, for example when the number of attempts doesn't match the number of successes.
 For each issuer that has auto-refresh enabled, CCF tracks an attempt for each try, and eventually a success, if the update completes.
 
-Operators can query those numbers via the :http:GET:`/node/jwt_metrics` endpoint.
+Operators can query those numbers via the :http:GET:`/node/jwt_keys/refresh/metrics` endpoint.

doc/build_apps/build_app.rst

@@ -7,7 +7,7 @@ Once an application is complete, it needs to be built into a shared object, and
 
 Using ``cmake``, an application can be built and then signed using the functions provided by CCF's ``cmake/ccf_app.cmake``. For example, for the ``js_generic`` JavaScript application:
 
-.. literalinclude:: ../../cmake/common.cmake
+.. literalinclude:: ../../CMakeLists.txt
     :language: cmake
     :start-after: SNIPPET_START: JS generic application
     :end-before: SNIPPET_END: JS generic application

doc/build_apps/example_rpc_api.rst

@@ -2,7 +2,6 @@ Example app RPC API
 ===================
 
 .. openapi:: ../schemas/app_openapi.json
-   :examples:
    :include:
       /app/log/.*
 

doc/build_apps/install_bin.rst

@@ -41,6 +41,8 @@ The dependencies required to build and run CCF apps can be conveniently installe
         
 This will install the latest release of CCF, but a specific release can also be specified with ``--extra-vars "ccf_ver=X.Y.Z"`` if desired.
 
+.. _Install:
+
 Installation from .deb
 ----------------------
 

doc/generate_config_rst.py

@@ -43,7 +43,9 @@ def _start_header_section(self, text):
     def start_section(self, header, prefix=""):
         if prefix:
             prefix = f"`{prefix}`"
-        self._start_header_section(f"{prefix}\ {header}")
+            self._start_header_section(f"{prefix}\ {header}")
+        else:
+            self._start_header_section(header)
         self._depth += 1
 
     def end_section(self):
@@ -111,8 +113,10 @@ def dump_property(
 
     t = obj.get("type")
 
-    if has_subobjs(obj):
-        output.start_section(f"``{prefix}{property_name}``")
+    if has_subobjs(obj) or len(path) == 0:
+        section_title = f"``{prefix}{property_name}``"
+
+        output.start_section(section_title)
         for condition in conditions:
             output.add_line(condition)
 
@@ -212,8 +216,9 @@ def gather_properties(obj, **kwargs):
             extra_conditions = []
             for k, cond in if_el["properties"].items():
                 assert "const" in cond, "Only 'const' conditions supported"
+                goal_s = monospace_literal(cond["const"])
                 extra_conditions.append(
-                    f"(Only applies if {''.join(path)}{k} is {monospace_literal(cond['const'])})"
+                    f"(Only applies if {''.join(path)}{k} is {goal_s})"
                 )
 
             gather_properties(obj["then"], conditions=conditions + extra_conditions)

doc/governance/gov_api_schemas/classic.rst

@@ -8,4 +8,3 @@ Any request calling a path with a ``/gov`` prefix which does not include the ``a
 .. warning:: This API is deprecated, and will be removed in a future release. See :doc:`/governance/gov_api_schemas/upgrading_from_classic` for a guide to upgrading to a more recent version.
 
 .. openapi:: ../../schemas/gov_openapi.json
-   :examples:

doc/governance/gov_api_schemas/upgrading_from_classic.rst

@@ -246,7 +246,7 @@ Service State
      - Read details of accepted JWKs and their issuers
    * - Classic
      - | :http:GET:`/gov/kv/jwt/issuers`
-       | :http:GET:`/gov/kv/jwt/public_signing_keys`
+       | ``GET /gov/kv/jwt/public_signing_keys``
    * - Replacement
      - :http:GET:`/gov/service/jwk`
    * - Notes

doc/operations/network.rst

@@ -4,13 +4,13 @@ Networking
 HTTP 
 ----
 
-All RPC interfaces for a given node (see :ref:`operations/configuration:``rpc_interfaces```) currently support HTTP/1.1. A specific RPC interface can also support HTTP/2 by setting the ``"app_protocol"`` configuration entry to ``"HTTP2"`` for that interface.
+All RPC interfaces for a given node (see :ref:`operations/configuration:``network.rpc_interfaces```) currently support HTTP/1.1. A specific RPC interface can also support HTTP/2 by setting the ``"app_protocol"`` configuration entry to ``"HTTP2"`` for that interface.
 
 .. warning:: HTTP/2 interfaces do not currently support client requests forwarding. Client requests that require forwarding to the primary node will return a `501 <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501>`_  HTTP error.
 
 Configuration
 ~~~~~~~~~~~~~
 
-Operators can cap the size of client HTTP requests (body and header) for each RPC interface in the :ref:`operations/configuration:``http_configuration``` configuration section. These configuration entries are optional and have sensible default values. 
+Operators can cap the size of client HTTP requests (body and header) for each RPC interface in the :ref:`operations/configuration:``network.rpc_interfaces.[name].http_configuration``` configuration section. These configuration entries are optional and have sensible default values. 
 
 If a client HTTP request breaches any of these values, the client is returned a `413 <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413>`_ or `431 <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/431>`_ HTTP error and the session is automatically closed by the CCF node.

doc/operations/operator_rpc_api.rst

@@ -3,5 +3,4 @@ Operator RPC API
 
 Operator RPCs are exposed under ``/node`` and do not require authentication.
 
-.. openapi:: ../schemas/node_openapi.json
-   :examples:
+.. openapi:: ../schemas/node_openapi.json

doc/operations/platforms/snp.rst

@@ -16,7 +16,7 @@ SNP attestation provide several fields needed to establish trust. Several deploy
 Confidential Azure Container Instance (ACI)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. note:: See `here <https://learn.microsoft.com/en-us/azure/container-instances/container-instances-tutorial-deploy-confidential-containers-cce-arm>`_ and `here <https://github.com/microsoft/confidential-aci-examples/blob/main/docs/Confidential_ACI_SCHEME.md>`_ for more information on the deployment of confidential containers in Azure.
+.. note:: See `here <https://learn.microsoft.com/en-us/azure/container-instances/container-instances-tutorial-deploy-confidential-containers-cce-arm>`__ and `here <https://github.com/microsoft/confidential-aci-examples/blob/main/docs/Confidential_ACI_SCHEME.md>`__ for more information on the deployment of confidential containers in Azure.
 
 Azure Confidential ACI provides a security context directory containing the following files.
 
@@ -32,7 +32,7 @@ AMD endorsements must be fetched, preferably from the THIM service, but configur
 Confidential Azure Kubernetes Service (AKS)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. note:: See `here <https://learn.microsoft.com/en-us/azure/aks/deploy-confidential-containers-default-policy>`_ for more information on the deployment of confidential containers in Azure.
+.. note:: See `here <https://learn.microsoft.com/en-us/azure/aks/deploy-confidential-containers-default-policy>`__ for more information on the deployment of confidential containers in Azure.
 
 Confidential AKS provides a security context directory containing the following file.
 
@@ -48,7 +48,7 @@ AMD endorsements must be fetched, preferably from the THIM service, but configur
 Non-Azure Deployment
 ~~~~~~~~~~~~~~~~~~~~
 
-For non-Azure deployments, the certificate chain for VCEK will need to be retrieved from an endorsement server, as specified in the :ref:`operations/configuration:``snp_endorsements_servers``` configuration section. For example, for the `well-known AMD endorsement server <https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/specifications/57230.pdf>`_, the value should be set to:
+For non-Azure deployments, the certificate chain for VCEK will need to be retrieved from an endorsement server, as specified in the :ref:`operations/configuration:``attestation.snp_endorsements_servers``` configuration section. For example, for the `well-known AMD endorsement server <https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/specifications/57230.pdf>`_, the value should be set to:
 
 .. code-block:: json
 

doc/operations/start_network.rst

@@ -29,7 +29,7 @@ When starting up, the node generates its own key pair and outputs the unendorsed
 
 .. note:: The service certificate should be distributed to users and members to be used as the certificate authority (CA) when establishing a TLS connection with any of the nodes part of the CCF network. When using ``curl``, this is passed as the ``--cacert`` argument.
 
-The initial constitution scripts, member certificates, public encryption keys and data files as well as the initial service configuration should be set in the :ref:`operations/configuration:``start``` section of the JSON configuration.
+The initial constitution scripts, member certificates, public encryption keys and data files as well as the initial service configuration should be set in the :ref:`operations/configuration:``command.start``` section of the JSON configuration.
 
 Once the first node is started, the network will be in its opening state and new nodes can join the network.
 
@@ -52,7 +52,7 @@ To add a new node to an existing opening network, other nodes should be started
 
 The joining node takes the certificate of the existing network to join via ``service_certificate_file`` configuration entry and initiates an enclave-to-enclave TLS connection to an existing node of the network as specified by ``join.target_rpc_address`` configuration entry.
 
-The join configuration option should be set in the :ref:`operations/configuration:``join``` section of the JSON configuration.
+The join configuration option should be set in the :ref:`operations/configuration:``command.join``` section of the JSON configuration.
 
 A new node can only join an existing CCF network if its SGX quote is valid  [#remote_attestation]_. and runs an enclave application that is :ref:`trusted by the consortium <governance/common_member_operations:Updating Code Version>`.
 

doc/use_apps/rpc_api.rst

@@ -10,7 +10,6 @@ Built-ins
 By default, CCF will also add some built-in endpoints:
 
 .. openapi:: ../schemas/app_openapi.json
-   :examples:
    :include:
       /app/api
       /app/tx

js/ccf-app/typedoc.json

@@ -9,7 +9,6 @@
     "src/historical.ts",
     "src/kv.ts",
     "src/polyfill.ts",
-    "src/openenclave.ts",
     "src/snp_attestation.ts"
   ],
   "out": "html",