Replace Sphinx with MkDocs

build-docs.sh

@@ -5,7 +5,6 @@ set -o nounset
 export OSS_PARAMS_FILENAME=../gso/oss-params-example.json
 export TESTING=true
 
-pip install sphinx_rtd_theme sphinxcontrib-jquery
+pip install mkdocstrings-python mkdocs_gen_files mkdocs-material mkdocs-literate-nav mkdocs-section-index
 
-cd docs
-sphinx-build source build
+mkdocs build

docs/overrides/partials/logo.html

+<img id="logo_light_mode" src="{{ config.theme.logo_light_mode | url }}" alt="logo">
+<img id="logo_dark_mode" src="{{ config.theme.logo_dark_mode | url }}" alt="logo">

docs/scripts/gen_ref_pages.py

+"""Generate the code reference pages.
+
+Source: https://mkdocstrings.github.io/recipes/
+"""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+root = Path(__file__).parent.parent
+src = root / "gso"
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src).with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1] == "__main__":
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        identifier = ".".join(parts)
+        print("::: " + identifier, file=fd)
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

docs/source/Makefile

-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = ../build
-
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-.PHONY: help Makefile
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/conf.py

-# -- Project information -----------------------------------------------------
-project = "GÉANT Service Orchestrator"
-copyright = "2023-2024, GÉANT Vereniging"
-author = "GÉANT Orchestration and Automation Team"
-
-# -- General configuration ---------------------------------------------------
-extensions = ["sphinx_rtd_theme", "sphinx.ext.autodoc", "sphinxcontrib.jquery"]
-
-templates_path = ["templates"]
-exclude_patterns = ["build", "Thumbs.db", ".DS_Store", "venv", "vale", "__init__.py"]
-
-# -- Options for HTML output -------------------------------------------------
-html_theme = "sphinx_rtd_theme"
-html_static_path = ["static"]
-html_theme_options = {
-    "style_nav_header_background": "rgb(0 63 95)",
-}
-html_css_files = ["custom.css"]
-html_js_files = ["custom.js"]
-html_logo = "static/geant_logo_white.svg"
-
-# Both the class' and the ``__init__`` method's docstring are concatenated and inserted.
-autoclass_content = "both"
-autodoc_typehints = "none"
-
-# Display todos by setting to True
-todo_include_todos = True

docs/source/glossary.rst

-Glossary of terms
-=================
-
-.. glossary::
-
-  AAI
-    Authentication and Authorisation Infrastructure
-
-  API
-    Application Programming Interface
-
-  BFD
-    Bi-directional Forwarding Detection
-
-  BGP
-    Border Gateway Protocol: a path vector routing protocol described in
-    `RFC 4271 <https://datatracker.ietf.org/doc/html/rfc4271>`_.
-
-  CIDR
-    Classless Inter-Domain Routing. A method for denoting IP ranges in the form of ``9.9.0.0/16`` or
-    ``fe80:1234:abcd::/48``.
-
-  CLI
-    Command Line Interface.
-
-  CNAME
-    A type of DNS record that is used as an alias from one hostname to another
-
-  CRUD
-    Create, Read, Update, Delete
-
-  DNS
-    The Domain Name System. Used for correlating domain names to IP information, among others.
-
-  FQDN
-    Fully Quantified Domain Name
-
-  GAP
-    The GÉANT Automation Platform
-
-  GSO
-    GÉANT Service Orchestrator
-
-  IAS
-    IAS
-
-  IPAM
-    IP Address Management
-
-  ISIS
-    Intermediate System to Intermediate System: a routing protocol described in
-    `RFC 7142 <https://datatracker.ietf.org/doc/html/rfc7142>`_.
-
-  ISO
-    International Organisation for Standardisation
-
-  JSON
-    JavaScript Object Notation
-
-  LACP
-    Link Aggregation Control Protocol
-
-  LAG
-    Link Aggregation: a bundle of multiple network connections.
-
-  LAN
-    Local Area Network
-
-  LLDP
-    Link Layer Discovery Protocol
-
-  LSO
-    Lightweight Service Orchestrator
-
-  NET
-    Network Entity Title: used for :term:`ISIS` routing.
-
-  NREN
-    National Research and Education Network
-
-  OIDC
-    OpenID Connect
-
-  OOB
-    Out-of-band access
-
-  OPA
-    Open Policy Agent
-
-  OSS
-    Operational Support Systems
-
-  SBP
-    Service Binding Point, a logical construct used in the orchestrator to attach a partner subscription to a physical
-    (set of) ports.
-
-  SDP
-    Service Demarcation Point: A logical construct used for modeling partner subscriptions. It models the link between
-    the physical and the service domains.
-
-  SNMP
-    Simple Network Management Protocol: a protocol that's used for gathering data, widely used for network management
-    and monitoring.
-
-  TWAMP
-    A Two-Way Active Measuring Protocol, as defined in `RFC 5357 <https://datatracker.ietf.org/doc/html/rfc5357>`_.
-
-  UUID
-    Universally Unique Identifier
-
-  VLAN
-    Virtual LAN
-
-  WAN
-    Wide Area Network
-
-  WFO
-    `Workflow Orchestrator <https://workfloworchestrator.org/>`_
-
-  Moodi
-    A service that does monitoring on demand during a workflow execution.
\ No newline at end of file

docs/source/index.rst

-GÉANT Service Orchestrator
-==========================
-
-Welcome to the documentation of the GÉANT Service Orchestrator, or :term:`GSO` for short.
-
-This documentation has the following sections:
-
-.. toctree::
-   :caption: Contents
-   :maxdepth: 2
-
-   quickstart
-   modules
-   glossary

docs/source/module/api/index.rst

-``gso.api``
-===========
-
-.. automodule:: gso.api
-   :members:
-   :show-inheritance:
-
-Subpackages
------------
-
-.. toctree::
-   :maxdepth: 2
-   :titlesonly:
-
-   v1/index

docs/source/module/api/v1/index.rst

-``gso.api.v1``
-==============
-
-.. automodule:: gso.api.v1
-   :members:
-   :show-inheritance:
-
-Submodules
-----------
-
-.. toctree::
-   :maxdepth: 2
-   :titlesonly:
-
-   subscriptions
-   network

docs/source/module/api/v1/network.rst

-``gso.api.v1.network``
-======================
-
-.. automodule:: gso.api.v1.network
-   :members:
-   :show-inheritance:

docs/source/module/api/v1/subscriptions.rst

-``gso.api.v1.subscriptions``
-============================
-
-.. automodule:: gso.api.v1.subscriptions
-   :members:
-   :show-inheritance:

docs/source/module/auth/api_key_auth.rst

-``gso.auth.api_key_auth``
-=========================
-
-.. automodule:: gso.auth.api_key_auth
-   :members:
-   :show-inheritance:

docs/source/module/auth/index.rst

-``gso.auth``
-============
-
-.. automodule:: gso.auth
-   :members:
-   :show-inheritance:
-
-Subpackages
------------
-
-.. toctree::
-   :maxdepth: 1
-
-   api_key_auth
-   oidc
-   opa

docs/source/module/auth/oidc.rst

-``gso.auth.oidc``
-=================
-
-.. automodule:: gso.auth.oidc
-   :members:
-   :show-inheritance:

docs/source/module/auth/opa.rst

-``gso.auth.opa``
-================
-
-.. automodule:: gso.auth.opa
-   :members:
-   :show-inheritance:

docs/source/module/cli/imports.rst

-``gso.cli.imports``
-===================
-
-.. automodule:: gso.cli.imports
-   :members:
-   :show-inheritance:

docs/source/module/cli/index.rst

-``gso.cli``
-===========
-
-.. automodule:: gso.cli
-   :members:
-   :show-inheritance:
-
-Submodules
-----------
-
-.. toctree::
-   :maxdepth: 2
-   :titlesonly:
-
-   imports
-   netbox

docs/source/module/cli/netbox.rst

-``gso.cli.netbox``
-==================
-
-.. automodule:: gso.cli.netbox
-   :members:
-   :show-inheritance:

docs/source/module/products/index.rst

-``gso.products``
-================
-
-.. automodule:: gso.products
-   :members:
-   :show-inheritance:
-
-Subpackages
------------
-
-.. toctree::
-   :maxdepth: 1
-
-   product_blocks/index
-   product_types/index

docs/source/module/products/product_blocks/bgp_session.rst

-``gso.products.product_blocks.bgp_session``
-===========================================
-
-.. automodule:: gso.products.product_blocks.bgp_session
-   :members:
-   :show-inheritance: