docs: move docs tooling to _tooling

.gitignore

@@ -17,3 +17,6 @@ styles/
 
 # direnv - folder-specific bash configuration
 .envrc
+
+# Python
+__pycache__/

.vscode/settings.json

@@ -49,7 +49,9 @@
         "docs",
         "_build",
         "--jobs",
-        "auto"
+        "auto",
+        "--conf-dir",
+        "docs"
     ],
     // default is "error", which doesn't show anything.
     "esbonio.logging.level": "warning"

MODULE.bazel

@@ -42,7 +42,7 @@ pip = use_extension("@rules_python//python/extensions:pip.bzl", "pip")
 pip.parse(
     hub_name = "pip_sphinx",
     python_version = PYTHON_VERSION,
-    requirements_lock = "//docs:requirements_lock.txt",
+    requirements_lock = "//docs:_tooling/requirements_lock.txt",
 )
 use_repo(pip, "pip_sphinx")
 

docs/BUILD

@@ -47,7 +47,7 @@ load("@rules_python//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs
 
 # all_requirements include esbonio which we don't need most of the time.
 # Hint: the names are e.g. "@@rules_python~~pip~pip_sphinx//esbonio:pkg"
-sphinx_requirements = [name for name in all_requirements if not "esbonio" in name] + [":extensions"]
+sphinx_requirements = [name for name in all_requirements if not "esbonio" in name]
 
 sphinx_docs(
     name = "docs",
@@ -74,15 +74,15 @@ sphinx_docs(
 
 sphinx_build_binary(
     name = "sphinx_build",
-    deps = sphinx_requirements,
+    deps = sphinx_requirements + [":extensions"],
 )
 
 py_library(
     name = "extensions",
-    srcs = [
-        "_extensions/layouts.py",
-        "_extensions/metamodel.py",
-    ],
+    srcs =
+        glob(["_tooling/conf_extras/*.py"]) + glob([
+            "_tooling/extensions/*.py",
+        ]),
     imports = ["."],
 )
 
@@ -93,8 +93,8 @@ py_library(
 # `bazel run //docs:requirements -- --upgrade`.
 compile_pip_requirements(
     name = "requirements",
-    src = "requirements.txt",
-    requirements_txt = "requirements_lock.txt",
+    src = "_tooling/requirements.txt",
+    requirements_txt = "_tooling/requirements_lock.txt",
     tags = [
         "manual",
     ],
@@ -120,7 +120,7 @@ pkg_tar(
 # Run-time build of documentation, incl. incremental build support.
 py_binary(
     name = "incremental",
-    srcs = ["incremental.py"],
+    srcs = ["_tooling/incremental.py"],
     deps = sphinx_requirements,
 )
 

docs/incremental.py → docs/_tooling/incremental.py

@@ -12,31 +12,23 @@
 # *******************************************************************************
 
 import os
-import sys
 
-try:
-    from sphinx.cmd.build import main as sphinx_main
-except ImportError:
-    sys.exit(
-        "This script must be run from Bazel via `bazel run //docs:incremental`"
-        " (sphinx not installed)."
-    )
-
-workspace = os.getenv("BUILD_WORKSPACE_DIRECTORY")
-if not workspace:
-    sys.exit(
-        "This script must be run from Bazel via `bazel run //docs:incremental`"
-        " (BUILD_WORKSPACE_DIRECTORY not set)."
-    )
+from sphinx.cmd.build import main as sphinx_main
 
 # sphinx will print relative paths to the current directory.
 # Change to the workspace root so that the paths are readable and clickable.
-os.chdir(workspace)
+workspace = os.getenv("BUILD_WORKSPACE_DIRECTORY")
+if workspace:
+    os.chdir(workspace)
+
+
 sphinx_main(
     [
-        "docs",
-        "_build",
+        "docs",  # src dir
+        "_build",  # out dir
         "--jobs",
         "auto",
+        "--conf-dir",
+        "docs",
     ]
 )

docs/requirements_lock.txt → docs/_tooling/requirements_lock.txt

@@ -143,7 +143,7 @@ docutils==0.20.1 \
 esbonio==0.16.5 \
     --hash=sha256:04ba926e3603f7b1fde1abc690b47afd60749b64b1029b6bce8e1de0bb284921 \
     --hash=sha256:acab2e16c6cf8f7232fb04e0d48514ce50566516b1f6fcf669ccf2f247e8b10f
-    # via -r docs/requirements.txt
+    # via -r docs/_tooling/requirements.txt
 idna==3.7 \
     --hash=sha256:028ff3aadf0609c1fd278d8ea3089299412a7a8b9bd005dd08b9f8285bcb5cfc \
     --hash=sha256:82fee1fc78add43492d3a1898bfa6d8a904cc97d8427f683ed8e798d07761aa0
@@ -241,7 +241,7 @@ platformdirs==4.3.6 \
 pydata-sphinx-theme==0.16.0 \
     --hash=sha256:18c810ee4e67e05281e371e156c1fb5bb0fa1f2747240461b225272f7d8d57d8 \
     --hash=sha256:721dd26e05fa8b992d66ef545536e6cbe0110afb9865820a08894af1ad6f7707
-    # via -r docs/requirements.txt
+    # via -r docs/_tooling/requirements.txt
 pygls==1.3.1 \
     --hash=sha256:140edceefa0da0e9b3c533547c892a42a7d2fd9217ae848c330c53d266a55018 \
     --hash=sha256:6e00f11efc56321bdeb6eac04f6d86131f654c7d49124344a9ebb968da3dd91e
@@ -380,7 +380,7 @@ sphinx==8.1.3 \
     --hash=sha256:09719015511837b76bf6e03e42eb7595ac8c2e41eeb9c29c5b755c6b677992a2 \
     --hash=sha256:43c1911eecb0d3e161ad78611bc905d1ad0e523e4ddc202a58a821773dc4c927
     # via
-    #   -r docs/requirements.txt
+    #   -r docs/_tooling/requirements.txt
     #   esbonio
     #   pydata-sphinx-theme
     #   sphinx-data-viewer
@@ -394,11 +394,11 @@ sphinx-data-viewer==0.1.5 \
 sphinx-design==0.6.1 \
     --hash=sha256:b11f37db1a802a183d61b159d9a202314d4d2fe29c163437001324fe2f19549c \
     --hash=sha256:b44eea3719386d04d765c1a8257caca2b3e6f8421d7b3a5e742c0fd45f84e632
-    # via -r docs/requirements.txt
+    # via -r docs/_tooling/requirements.txt
 sphinx-needs==4.1.0 \
     --hash=sha256:7d40e9c29353d9784f469b2093412846060cda4f3b55127ac58a2692c3381ef9 \
     --hash=sha256:8ae21e10515249aaba3dabd7fd66afdedd1160ecbc5816337fb6ed82aca293b7
-    # via -r docs/requirements.txt
+    # via -r docs/_tooling/requirements.txt
 sphinxcontrib-applehelp==1.0.8 \
     --hash=sha256:c40a4f96f3776c4393d933412053962fac2b84f4c99a7982ba42e09576a70619 \
     --hash=sha256:cb61eb0ec1b61f349e5cc36b2028e9e7ca765be05e49641c97241274753067b4

docs/conf.py

@@ -16,9 +16,12 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# from process.process_model_configuration import *
-from _extensions import metamodel, layouts
+import sys
 
+# sys.path extension for local files is needed, because the conf.py file is not
+# executed, but imported by Sphinx
+sys.path.insert(0, ".")
+from _tooling.conf_extras import layouts, metamodel
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information