Doc versioning

.azure-pipelines-gh-pages.yml

@@ -32,9 +32,8 @@ jobs:
         source env/bin/activate
         pip install wheel
         pip install -U -r requirements.txt
-        make html
+        sphinx-multiversion doc build/html
       displayName: Sphinx
-      workingDirectory: sphinx
 
     - script: |
         git init
@@ -43,7 +42,7 @@ jobs:
         git add .
         git commit -m "[ci skip] commit generated documentation"
       displayName: 'Commit pages'
-      workingDirectory: sphinx/build/html
+      workingDirectory: build/html
 
     - task: DownloadSecureFile@1
       inputs:
@@ -62,9 +61,9 @@ jobs:
       condition: |
         and(not(eq(variables['Build.Reason'], 'PullRequest')),
             eq(variables['Build.SourceBranch'], 'refs/heads/master'))
-      workingDirectory: sphinx/build/html
+      workingDirectory: build/html
 
     - script: rm deploy_key || true
       displayName: 'Make sure key is removed'
-      workingDirectory: sphinx/build/html
+      workingDirectory: build/html
       condition: always()

.azure-pipelines-templates/checks.yml

@@ -5,7 +5,7 @@ jobs:
   ${{ insert }}: ${{ parameters.env }}
 
   variables:
-    python_files: sphinx/ tests/ notice-check.py
+    python_files: tests/ notice-check.py
 
   steps:
     - checkout: self

.azure-pipelines.yml

@@ -4,17 +4,6 @@ trigger:
     include:
       - master
       - 'refs/tags/v*'
-  paths:
-    exclude:
-      - 'README.md'
-      - 'CCF-TECHNICAL-REPORT.pdf'
-      - 'Doxyfile'
-      - 'THIRD_PARTY_NOTICES.txt'
-      - 'getting_started/'
-      - 'sphinx/'
-      - '.github/'
-      - '.azure-pipelines-gh-pages.yml'
-      - 'LICENSE'
 
 pr:
   autoCancel: true

CMakeLists.txt

@@ -583,7 +583,7 @@ if(BUILD_TESTS)
       PYTHON_SCRIPT ${CMAKE_SOURCE_DIR}/tests/schema.py
       CONSENSUS ${CONSENSUS}
       ADDITIONAL_ARGS -p liblogging --schema-dir
-                      ${CMAKE_SOURCE_DIR}/sphinx/source/schemas
+                      ${CMAKE_SOURCE_DIR}/doc/schemas
     )
 
     add_e2e_test(

doc/_templates/docs-navbar.html

@@ -0,0 +1,44 @@
+<div class="container-xl">
+
+    {% if logo %}
+    <a class="navbar-brand" href="{{ pathto(master_doc) }}">
+      <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="logo">
+    </a>
+    {% endif %}
+    <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbar-menu" aria-controls="navbar-menu" aria-expanded="false" aria-label="Toggle navigation">
+        <span class="navbar-toggler-icon"></span>
+    </button>
+
+    <div id="navbar-menu" class="col-11 collapse navbar-collapse">
+      <ul id="navbar-main-elements" class="navbar-nav mr-auto">
+        {% set nav = get_nav_object(maxdepth=1, collapse=True) %}
+        {% for main_nav_item in nav %}
+        <li class="nav-item {% if main_nav_item.active%}active{% endif %}">
+            <a class="nav-link" href="{{ main_nav_item.url }}">{{ main_nav_item.title }}</a>
+        </li>
+        {% endfor %}
+        {% for external_link in theme_external_links %}
+        <li class="nav-item">
+            <a class="nav-link nav-external" href="{{ external_link.url }}">{{ external_link.name }}<i class="fas fa-external-link-alt"></i></a>
+        </li>
+        {% endfor %}
+      </ul>
+
+      <ul class="navbar-nav">
+        {% if theme_github_url | length > 2 %}
+          <li class="nav-item">
+            <a class="nav-link" href="{{ theme_github_url }}" target="_blank" rel="noopener">
+              <span><i class="fab fa-github-square"></i></span>
+            </a>
+          </li>
+        {% endif %}
+        {% if theme_twitter_url | length > 2 %}
+          <li class="nav-item">
+            <a class="nav-link" href="{{ theme_twitter_url }}" target="_blank" rel="noopener">
+              <span><i class="fab fa-twitter-square"></i></span>
+            </a>
+          </li>
+        {% endif %}
+      </ul>
+    </div>
+</div>

doc/_templates/docs-sidebar.html

@@ -0,0 +1,46 @@
+{% if theme_search_bar_position == "sidebar" %}
+  {%- include "search-field.html" %}
+{% endif %}
+
+<nav class="bd-links" id="bd-docs-nav" aria-label="Main navigation">
+
+  <div class="bd-toc-item active">
+  {% set nav = get_nav_object(maxdepth=3, collapse=True) %}
+
+  <ul class="nav bd-sidenav">
+      {% for main_nav_item in nav %}
+      {% if main_nav_item.active %}
+        {% for nav_item in main_nav_item.children %}
+          {% if nav_item.children %}
+
+              <li class="{% if nav_item.active%}active{% endif %}">
+                  <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
+                  <ul>
+                  {% for nav_item in nav_item.children %}
+                      <li class="{% if nav_item.active%}active{% endif %}">
+                          <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
+                      </li>
+                  {% endfor %}
+                  </ul>
+              </li>
+          {% else %}
+              <li class="{% if nav_item.active%}active{% endif %}">
+                  <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
+              </li>
+          {% endif %}
+        {% endfor %}
+      {% endif %}
+      {% endfor %}
+    </ul>
+
+    {% if versions %}
+    {%- for item in versions %}
+      <ul>
+        <li>
+          <a href="{{ item.url }}" class="badge">{{ item.name }}</a>
+        </li>
+      </ul>
+    {%- endfor %}
+    {% endif %}
+
+</nav>

sphinx/source/concepts.rst → doc/concepts.rst

@@ -1,5 +1,5 @@
-CCF Concepts
-============
+Concepts
+========
 
 This page provides a broad overview of the key concepts and components of CCF.
 
@@ -12,12 +12,12 @@ Network and Nodes
 
 A CCF network consists of several nodes, each running on top of a Trusted Execution Environment (:term:`TEE`), or enclave, such as :term:`SGX`. As such, a CCF network is decentralised and highly-available.
 
-Nodes are run and maintained by :term:`operators`. However, nodes must be trusted by the consortium of members before participating in a CCF network.
+Nodes are run and maintained by :term:`Operators`. However, nodes must be trusted by the consortium of members before participating in a CCF network.
 
 Application
 -----------
 
-Each node runs the same application (a.k.a. transaction engine). An application is a collection of endpoints that can be triggered by trusted :term:`users`' commands over :term:`TLS`.
+Each node runs the same application (a.k.a. transaction engine). An application is a collection of endpoints that can be triggered by trusted :term:`Users`' commands over :term:`TLS`.
 
 Each endpoint mutates an in-enclave-memory Key-Value Store that is replicated across all nodes in the network. Changes to the Key-Value Store must be agreed by a variable number of nodes, depending on the consensus algorithm selected (either Raft or PBFT), before being applied.
 
@@ -35,7 +35,7 @@ The integrity of the ledger is guaranteed by a Merkle tree whose root is periodi
 Governance
 ----------
 
-A CCF network is governed by a consortium of :term:`members`. The :term:`constitution`, recorded in the ledger itself, defines a set of rules that members must follow.
+A CCF network is governed by a consortium of :term:`Members`. The :term:`Constitution`, recorded in the ledger itself, defines a set of rules that members must follow.
 
 Members can submit proposals to modify the state of the Key-Value Store. For example, members can vote to allow a new trusted user to issue requests to the application or to add a new member to the consortium.
 

sphinx/source/conf.py → doc/conf.py

@@ -49,6 +49,7 @@
     "sphinxcontrib.mermaid",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.githubpages",
+    "sphinx_multiversion",
 ]
 
 autosectionlabel_prefix_document = True
@@ -86,7 +87,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+html_theme = "pydata_sphinx_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -176,13 +177,46 @@
 # -- Breathe configuration
 
 # Setup the breathe extension
-breathe_projects = {"CCF": "../../doxygen/xml"}
+breathe_projects = {"CCF": "../doxygen/xml"}
 breathe_default_project = "CCF"
 
+"""
 html_context = {
     "source_url_prefix": "https://github.com/Microsoft/CCF",
     "display_github": True,
     "github_user": "Microsoft",
     "github_repo": "CCF",
-    "github_version": "master/sphinx/source/",
+    "github_version": "master/doc/",
 }
+"""
+
+# Set up multiversion extension
+
+smv_tag_whitelist = r"^v.*$"
+smv_branch_whitelist = r"^master$"
+smv_remote_whitelist = None
+smv_outputdir_format = "{ref.name}"
+
+# PyData theme options
+
+html_logo = "_static/ccf.svg"
+html_favicon = "_static/favicon.ico"
+
+html_theme_options = {
+    "github_url": "https://github.com/Microsoft/CCF",
+    "use_edit_page_button": True,
+}
+
+html_context = {
+    "github_user": "Microsoft",
+    "github_repo": "CCF",
+    "github_version": "master",
+    "doc_path": "doc/",
+}
+
+
+def setup(self):
+    import subprocess
+
+    subprocess.run(["rm", "doxygen"], check=False)
+    subprocess.run(["doxygen"], check=True)

sphinx/source/developers/build_app.rst → doc/developers/build_app.rst

@@ -5,14 +5,14 @@ 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 ``CCF/cmake/ccf.cmake``. For example, for the ``lua_generic`` application:
 
-.. literalinclude:: ../../../cmake/common.cmake
+.. literalinclude:: ../../cmake/common.cmake
     :language: cmake
     :start-after: SNIPPET_START: Lua generic application
     :end-before: SNIPPET_END: Lua generic application
 
 The :term:`Open Enclave` configuration file (``oe_sign.conf``) should be placed under the same directory as the source files for the application. For example:
 
-.. literalinclude:: ../../../src/apps/logging/oe_sign.conf
+.. literalinclude:: ../../src/apps/logging/oe_sign.conf
 
 .. note:: The `Open Enclave documentation <https://github.com/openenclave/openenclave/blob/master/docs/GettingStartedDocs/buildandsign.md#signing-the-enclave>`_ provides details about the enclave settings in the ``oe_sign.conf`` configuration file.
 

sphinx/source/developers/cryptography.rst → doc/developers/cryptography.rst

@@ -46,7 +46,7 @@ Authenticated encryption in CCF relies on AES256-GCM. Ledger authentication reli
 
 Public-key certificates, signatures, and ephemeral Diffie-Hellman key exchanges all rely on elliptic curves. The supported curves are listed in `tls/curve.h`:
 
-    .. literalinclude:: ../../../src/tls/curve.h
+    .. literalinclude:: ../../src/tls/curve.h
         :language: cpp
         :start-after: SNIPPET_START: supported_curves
         :end-before: SNIPPET_END: supported_curves

sphinx/source/developers/demo.rst → doc/developers/demo.rst

@@ -5,7 +5,7 @@ This document explains how the Python testing infrastructure is used to run a co
 
 The script ``tests/e2e_scenarios.py`` reads a test scenario from json. This json file can specify which app the network should run, how many nodes it should create, and the list of transactions to run. ``tests/simple_logging_scenario.json`` is an example scenario file showing the expected format:
 
-.. literalinclude:: ../../../tests/simple_logging_scenario.json
+.. literalinclude:: ../../tests/simple_logging_scenario.json
     :language: json
 
 To see how this is run in the main test suite, look at the `Test command` used by CTest:
@@ -32,15 +32,15 @@ To run manually with your own scenario:
 
 This first loads the scenario from the given json file, extracting setup fields:
 
-.. literalinclude:: ../../../tests/e2e_scenarios.py
+.. literalinclude:: ../../tests/e2e_scenarios.py
     :language: python
     :start-after: SNIPPET_START: parsing
     :end-before: SNIPPET_END: parsing
     :dedent: 2
 
 Given the above ``scenario.json`` this should create 2 nodes on the local machine running the ``logging`` example app. The script then creates the requested CCF network:
 
-.. literalinclude:: ../../../tests/e2e_scenarios.py
+.. literalinclude:: ../../tests/e2e_scenarios.py
     :language: python
     :start-after: SNIPPET_START: create_network
     :end-before: SNIPPET_END: create_network

sphinx/source/developers/index.rst → doc/developers/index.rst

@@ -1,9 +1,9 @@
-Writing CCF Applications
-========================
+Building Apps
+=============
 
 This section describes how CCF applications can be developed and deployed to a CCF network.
 
-Applications can be written in C++ or Lua (see :ref:`developers/example:Example Application`). An application consists of a collection of endpoints that can be triggered by :term:`users`. Each endpoint can define an :ref:`developers/logging_cpp:API Schema` to validate user requests.
+Applications can be written in C++ or Lua (see :ref:`developers/example:Example Application`). An application consists of a collection of endpoints that can be triggered by :term:`Users`. Each endpoint can define an :ref:`developers/logging_cpp:API Schema` to validate user requests.
 
 These endpoints mutate the state of a unique :ref:`developers/kv/index:Key-Value Store` that represents the internal state of the application. Applications define a set of ``Maps`` (see :ref:`developers/kv/kv_how_to:Creating a Map`), mapping from a key to a value. When an application endpoint is triggered, the effects on the Store are committed atomically.