docs: Introduce Bazel-based docgen

Bug: 318892911
Change-Id: I209acd919bbbdea38e553e361e280d850ad5f0d4
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/237877
Commit-Queue: Kayce Basques <[email protected]>
Presubmit-Verified: CQ Bot Account <[email protected]>
Reviewed-by: Armando Montanez <[email protected]>
Reviewed-by: Keir Mierle <[email protected]>
Reviewed-by: Ted Pudlik <[email protected]>
Lint: Lint 🤖 <[email protected]>

BUILD.bazel

@@ -25,6 +25,7 @@ exports_files(
 exports_files(
     [
         "pigweed.json",
+        "PIGWEED_MODULES",
         "tsconfig.json",
     ],
     visibility = [":__subpackages__"],

docs/BUILD.bazel

@@ -12,4 +12,47 @@
 # License for the specific language governing permissions and limitations under
 # the License.
 
-# TODO(mohrr) figure out how to do this in bazel
+load("@pigweed//pw_build:compatibility.bzl", "incompatible_with_mcu")
+load("@rules_python//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs")
+
+package(default_visibility = ["//visibility:public"])
+
+licenses(["notice"])
+
+exports_files([
+    "module_metadata.json",
+    "module_metadata_schema.json",
+])
+
+sphinx_docs(
+    name = "docs",
+    srcs = [
+        "index.rst",
+        "modules.rst",
+    ],
+    config = "conf.py",
+    formats = [
+        "html",
+    ],
+    sphinx = ":sphinx-build",
+    strip_prefix = "docs/",
+    target_compatible_with = incompatible_with_mcu(),
+)
+
+sphinx_build_binary(
+    name = "sphinx-build",
+    target_compatible_with = incompatible_with_mcu(),
+    deps = [
+        "//pw_console/py:pw_console",
+        "//pw_docgen/py:pw_docgen",
+        "@python_packages//breathe",
+        "@python_packages//pydata_sphinx_theme",
+        "@python_packages//sphinx",
+        "@python_packages//sphinx_argparse",
+        "@python_packages//sphinx_copybutton",
+        "@python_packages//sphinx_design",
+        "@python_packages//sphinx_reredirects",
+        "@python_packages//sphinx_sitemap",
+        "@python_packages//sphinxcontrib_mermaid",
+    ],
+)

docs/BUILD.gn

@@ -58,6 +58,7 @@ pw_doc_group("core_docs") {
     "contributing/docs/changelog.rst",
     "contributing/docs/index.rst",
     "contributing/docs/modules.rst",
+    "contributing/docs/quickstart.rst",
     "contributing/docs/website.rst",
     "contributing/index.rst",
     "embedded_cpp_guide.rst",

docs/contributing/docs/index.rst

@@ -5,12 +5,21 @@ Docs contributors
 =================
 Authoring guidelines and style guides for ``pigweed.dev`` contributors.
 
+.. grid:: 1
+
+   .. grid-item-card:: :octicon:`list-ordered` Docs contributor quickstart
+      :link: contrib-docs-quickstart
+      :link-type: ref
+      :class-item: sales-pitch-cta-primary
+
+      How to contribute updates to ``pigweed.dev`` content.
+
 .. grid:: 2
 
    .. grid-item-card:: :octicon:`checklist` Module docs guidelines
       :link: docs-contrib-docs-modules
       :link-type: ref
-      :class-item: sales-pitch-cta-primary
+      :class-item: sales-pitch-cta-secondary
 
       How to structure and write docs for Pigweed modules.
 
@@ -62,6 +71,7 @@ Authoring guidelines and style guides for ``pigweed.dev`` contributors.
    :maxdepth: 1
    :hidden:
 
+   quickstart
    modules
    Writing <../../style/writing>
    reStructuredText <../../style/rest>

docs/contributing/docs/quickstart.rst

@@ -0,0 +1,55 @@
+.. _contrib-docs-quickstart:
+
+===========================
+Docs contributor quickstart
+===========================
+This quickstart shows you how to contribute updates to ``pigweed.dev``
+content.
+
+.. important::
+
+   This guide is incomplete. If you need to make content updates **right now**,
+   follow the guidance in :ref:`docs-get-started-upstream`. The rest of this
+   quickstart focuses on the new, work-in-progress Bazel-based docs system.
+   You should ignore this quickstart unless a Pigweed teammate has specifically
+   pointed you here.
+
+.. _contrib-docs-quickstart-setup:
+
+-----------------------------------
+Set up your development environment
+-----------------------------------
+#. Complete :ref:`docs-first-time-setup`.
+
+#. :ref:`docs-install-bazel`.
+
+.. _contrib-docs-quickstart-build:
+
+--------------
+Build the docs
+--------------
+.. code-block:: console
+
+   bazelisk build //docs/...
+
+.. _contrib-docs-quickstart-preview:
+
+---------------------------------
+Locally preview the rendered docs
+---------------------------------
+.. code-block:: console
+
+   bazelisk run //docs:docs.serve
+
+A message like this should get printed to ``stdout``:
+
+.. code-block:: console
+
+   Serving...
+     Address: http://0.0.0.0:8000
+     Serving directory: /home/kayce/pigweed/pigweed/bazel-out/k8-fastbuild/bin/docs/docs/_build/html
+         url: file:///home/kayce/pigweed/pigweed/bazel-out/k8-fastbuild/bin/docs/docs/_build/html
+     Server CWD: /home/kayce/.cache/bazel/_bazel_kayce/9659373b1552c281136de1c8eeb3080d/execroot/_main/bazel-out/k8-fastbuild/bin/docs/docs.serve.runfiles/_main
+
+You can access the rendered docs at the URL that's printed next to
+**Address**.

pw_docgen/py/BUILD.bazel

@@ -0,0 +1,50 @@
+# Copyright 2024 The Pigweed Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+load("@pigweed//pw_build:compatibility.bzl", "incompatible_with_mcu")
+load("@rules_python//python:defs.bzl", "py_library")
+
+package(default_visibility = ["//visibility:public"])
+
+py_library(
+    name = "pw_docgen",
+    srcs = [
+        "pw_docgen/__init__.py",
+        "pw_docgen/sphinx/__init__.py",
+        "pw_docgen/sphinx/bug.py",
+        "pw_docgen/sphinx/google_analytics.py",
+        "pw_docgen/sphinx/kconfig.py",
+        "pw_docgen/sphinx/module_metadata.py",
+        "pw_docgen/sphinx/modules_index.py",
+        "pw_docgen/sphinx/pigweed_live.py",
+        "pw_docgen/sphinx/pw_status_codes.py",
+        "pw_docgen/sphinx/seed_metadata.py",
+    ],
+    # TODO: https://pwbug.dev/371563295 - Remove these data dependencies after
+    # pigweed.dev-specific extensions have been moved out of pw_docgen.
+    data = [
+        "//:PIGWEED_MODULES",
+        "//docs:module_metadata.json",
+        "//docs:module_metadata_schema.json",
+    ],
+    imports = ["."],
+    target_compatible_with = incompatible_with_mcu(),
+    deps = [
+        "//pw_status/py:pw_status",
+        "@python_packages//kconfiglib",
+        "@python_packages//pytz",
+        "@python_packages//sphinx",
+        "@rules_python//python/runfiles",
+    ],
+)

pw_docgen/py/pw_docgen/sphinx/module_metadata.py

@@ -70,12 +70,20 @@
 # The module metadata is exposed as a global because it's used as read-only
 # data. Opening and reading the metadata file in one of the event handlers
 # would cause hundreds of filesystem reads on each build because those event
-# handlers fire once for each docs page.
-metadata_file = 'docs/module_metadata.json'
-schema_file = 'docs/module_metadata_schema.json'
-with open(f'{os.environ["PW_ROOT"]}/{schema_file}', 'r') as f:
+# handlers fire once for each docs page that's built.
+try:  # Bazel location for the data
+    from python.runfiles import runfiles  # type: ignore
+
+    r = runfiles.Create()
+    schema_file = r.Rlocation('pigweed/docs/module_metadata_schema.json')
+    r = runfiles.Create()
+    metadata_file = r.Rlocation('pigweed/docs/module_metadata.json')
+except ImportError:  # GN location for the data
+    schema_file = f'{os.environ["PW_ROOT"]}/docs/module_metadata_schema.json'
+    metadata_file = f'{os.environ["PW_ROOT"]}/docs/module_metadata.json'
+with open(schema_file, 'r') as f:
     schema = json.load(f)
-with open(f'{os.environ["PW_ROOT"]}/{metadata_file}', 'r') as f:
+with open(metadata_file, 'r') as f:
     metadata = json.load(f)
 # Make sure the metadata matches its schema. Raise an uncaught exception
 # if not.

pw_docgen/py/pw_docgen/sphinx/modules_index.py

@@ -20,10 +20,20 @@
 from sphinx.application import Sphinx
 
 
-with open(f'{os.environ["PW_ROOT"]}/PIGWEED_MODULES', 'r') as f:
+try:  # Bazel location for the data
+    from python.runfiles import runfiles  # type: ignore
+
+    r = runfiles.Create()
+    modules_file = r.Rlocation('pigweed/PIGWEED_MODULES')
+    r = runfiles.Create()
+    metadata_file = r.Rlocation('pigweed/docs/module_metadata.json')
+except ImportError:  # GN location for the data
+    modules_file = f'{os.environ["PW_ROOT"]}/PIGWEED_MODULES'
+    metadata_file = f'{os.environ["PW_ROOT"]}/docs/module_metadata.json'
+with open(modules_file, 'r') as f:
     # The complete, authoritative list of modules.
     complete_pigweed_modules_list = f.read().splitlines()
-with open(f'{os.environ["PW_ROOT"]}/docs/module_metadata.json', 'r') as f:
+with open(metadata_file, 'r') as f:
     # Module metadata such as supported languages and status.
     metadata = json.load(f)