docs/sphinx/BUILD.bazel

# Copyright 2025 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("@bazel_skylib//rules:copy_directory.bzl", "copy_directory")
load("@sphinxdocs//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs")
load("@sphinxdocs//sphinxdocs:sphinx_docs_library.bzl", "sphinx_docs_library")
load("//pw_build:compatibility.bzl", "incompatible_with_mcu")

licenses(["notice"])

package(default_visibility = ["//docs:__subpackages__"])

sphinx_docs_library(
    name = "extensions",
    srcs = [
        "_extensions/bug.py",
        "_extensions/cs.py",
        "_extensions/module_metadata.py",
        "_extensions/modules_index.py",
        "_extensions/pigweed_live.py",
        "_extensions/seed_metadata.py",
        "_extensions/sitemap.py",
        "_extensions/toctree.py",
    ],
    target_compatible_with = incompatible_with_mcu(),
    visibility = ["//visibility:private"],
)

sphinx_docs_library(
    name = "static",
    srcs = [
        "_static/css/pigweed.css",
        "_static/js/pigweed.js",
        # TODO: b/525058207 - Enable images.
        # "_static/svg/pw_kernel-tour-dark.svg",
        # "_static/svg/pw_kernel-tour-light.svg",
    ],
    visibility = ["//visibility:private"],
)

copy_directory(
    name = "rust_files",
    src = "//pw_rust:docs_dir",
    out = "rustdoc",
    visibility = ["//visibility:private"],
)

sphinx_docs_library(
    name = "rust",
    srcs = [":rust_files"],
    prefix = "rustdoc/",
    target_compatible_with = incompatible_with_mcu(),
    visibility = ["//visibility:private"],
)

sphinx_docs_library(
    name = "content",
    srcs = [
        "api/index.rst",
        "index.rst",
        "module_metadata.json",
        "module_metadata_schema.json",
        "modules.rst",
        "redirects.json",
        # TODO: b/388905812 - Delete this file.
        "size_report_notice",
        "targets.rst",
        "third_party_support.rst",
        "toolchain.rst",
        "blog/01-kudzu.rst",
        "blog/02-bazel-feature-flags.rst",
        "blog/03-pigweed-sdk.rst",
        "blog/04-fixed-point.rst",
        "blog/05-coroutines.rst",
        "blog/06-better-cpp-toolchains.rst",
        "blog/07-bazelcon-2024.rst",
        "blog/08-bazel-docgen.rst",
        "blog/09-bazel-relative-toolchain-paths.rst",
        "blog/index.rst",
        "blog/rss.xml",
        "build/bazel/compatibility.rst",
        "build/bazel/index.rst",
        "build/bazel/install.rst",
        "build/bazel/integration/index.rst",
        "build/bazel/integration/modules.rst",
        "build/bazel/integration/setup.rst",
        "build/bazel/dependencies.rst",
        "build/bazel/mcu-setup.rst",
        "build/bazel/quickstart.rst",
        "build/index.rst",
        "build/cmake/api.rst",
        "build/cmake/index.rst",
        "build/cmake/integration/index.rst",
        "build/cmake/quickstart.rst",
        "build/gn/index.rst",
        "build/gn/python.rst",
        "build/overview.rst",
        "code_of_conduct.rst",
        "code_reviews.rst",
        "community/index.rst",
        "concepts/index.rst",
        "contributing/build.rst",
        "contributing/docs/build.rst",
        "contributing/docs/changelog.rst",
        "contributing/docs/doxygen.rst",
        "contributing/docs/examples.rst",
        "contributing/docs/index.rst",
        "contributing/docs/modules.rst",
        "contributing/docs/website.rst",
        "contributing/index.rst",
        "embedded_cpp_guide.rst",
        "facades.rst",
        "faq.rst",
        "get_started/analysis.rst",
        "get_started/first_time_setup.rst",
        "get_started/github_actions.rst",
        "get_started/index.rst",
        "get_started/zephyr.rst",
        "glossary.rst",
        "infra/bazel_lockfile.rst",
        "infra/ci_cq_intro.rst",
        "infra/glossary.rst",
        "infra/index.rst",
        "infra/rollers.rst",
        "layout/layout.html",
        "mission.rst",
        "module_structure.rst",
        "os/index.rst",
        "os/zephyr/backends.rst",
        "os/zephyr/index.rst",
        "os/zephyr/setup.rst",
        "os/zephyr/features.rst",
        "os/freertos/backends.rst",
        "os/freertos/index.rst",
        "os/freertos/setup.rst",
        "os/freertos/features.rst",
        "os/threadx/backends.rst",
        "os/threadx/index.rst",
        "os/threadx/setup.rst",
        "os/threadx/features.rst",
        "os/embos/backends.rst",
        "os/embos/index.rst",
        "os/embos/setup.rst",
        "os/embos/features.rst",
        "os/stl/backends.rst",
        "os/stl/index.rst",
        "os/baremetal/backends.rst",
        "os/baremetal/index.rst",
        "overview.rst",
        "showcases/index.rst",
        "showcases/sense/analysis.rst",
        "showcases/sense/automate.rst",
        "showcases/sense/bazel_cloud.rst",
        "showcases/sense/build.rst",
        "showcases/sense/code_intelligence.rst",
        "showcases/sense/crash_handler.rst",
        "showcases/sense/device_tests.rst",
        "showcases/sense/explore.rst",
        "showcases/sense/factory.rst",
        "showcases/sense/flash.rst",
        "showcases/sense/host_sim.rst",
        "showcases/sense/host_tests.rst",
        "showcases/sense/index.rst",
        "showcases/sense/intro.rst",
        "showcases/sense/outro.rst",
        "showcases/sense/production.rst",
        "showcases/sense/rpc.rst",
        "showcases/sense/setup.rst",
        "showcases/sense/web.rst",
        "size_optimizations.rst",
        "style/bazel.rst",
        "style/cli.rst",
        "style/commit_message.rst",
        "style/cpp.rst",
        "style/doxygen.rst",
        "style/protobuf.rst",
        "style/python.rst",
        "style/rest.rst",
        "style/writing.rst",
        "style_guide.rst",
        "testing/cpp_type_equivalence_classes.rst",
        "testing/index.rst",
        "//:extra_docs_inputs",
        "//docker:docs",
        "//docs/doxygen:docs",
        "//docs/sphinx/changelog:docs",
        "//kudzu:docs",
        # start (sentinel for pw module create)
        "//pw_alignment:docs",
        "//pw_allocator:docs",
        "//pw_allocator_zephyr:docs",
        "//pw_analog:docs",
        "//pw_android_toolchain:docs",
        "//pw_arduino_build:docs",
        "//pw_assert:docs",
        "//pw_assert_basic:docs",
        "//pw_assert_fuchsia:docs",
        "//pw_assert_log:docs",
        "//pw_assert_tokenized:docs",
        "//pw_assert_trap:docs",
        "//pw_assert_zephyr:docs",
        "//pw_async:docs",
        "//pw_async2:docs",
        "//pw_async_basic:docs",
        "//pw_async_fuchsia:docs",
        "//pw_atomic:docs",
        "//pw_base64:docs",
        "//pw_bloat:docs",
        "//pw_blob_store:docs",
        "//pw_bluetooth:docs",
        "//pw_bluetooth_hci:docs",
        "//pw_bluetooth_profiles:docs",
        "//pw_bluetooth_proxy:docs",
        "//pw_bluetooth_sapphire:docs",
        "//pw_boot:docs",
        "//pw_boot_cortex_m:docs",
        "//pw_build:docs",
        "//pw_build_android:docs",
        "//pw_build_info:docs",
        "//pw_build_mcuxpresso:docs",
        "//pw_bytes:docs",
        "//pw_change:docs",
        "//pw_channel:docs",
        "//pw_checksum:docs",
        "//pw_chre:docs",
        "//pw_chrono:docs",
        "//pw_chrono_embos:docs",
        "//pw_chrono_freertos:docs",
        "//pw_chrono_rp2040:docs",
        "//pw_chrono_stl:docs",
        "//pw_chrono_threadx:docs",
        "//pw_chrono_zephyr:docs",
        "//pw_cli:docs",
        "//pw_cli_analytics:docs",
        "//pw_clock_tree:docs",
        "//pw_clock_tree_mcuxpresso:docs",
        "//pw_compilation_testing:docs",
        "//pw_config_loader:docs",
        "//pw_console:docs",
        "//pw_containers:docs",
        "//pw_cpu_exception:docs",
        "//pw_cpu_exception_cortex_m:docs",
        "//pw_cpu_exception_risc_v:docs",
        "//pw_crypto:docs",
        "//pw_digital_io:docs",
        "//pw_digital_io_linux:docs",
        "//pw_digital_io_mcuxpresso:docs",
        "//pw_digital_io_rp2040:docs",
        "//pw_digital_io_zephyr:docs",
        "//pw_display:docs",
        "//pw_dma_mcuxpresso:docs",
        "//pw_docgen:docs",
        "//pw_doctor:docs",
        "//pw_elf:docs",
        "//pw_emu:docs",
        "//pw_enum:docs",
        "//pw_env_setup:docs",
        "//pw_env_setup/bazel/cipd:docs",
        "//pw_env_setup_zephyr:docs",
        "//pw_file:docs",
        "//pw_flatbuffers:docs",
        "//pw_format:docs",
        "//pw_fortifier:docs",
        "//pw_function:docs",
        "//pw_fuzzer:docs",
        "//pw_grpc:docs",
        "//pw_hdlc:docs",
        "//pw_hex_dump:docs",
        "//pw_i2c:docs",
        "//pw_i2c_linux:docs",
        "//pw_i2c_mcuxpresso:docs",
        "//pw_i2c_rp2040:docs",
        "//pw_i2c_zephyr:docs",
        "//pw_ide:docs",
        "//pw_interrupt:docs",
        "//pw_interrupt_cortex_m:docs",
        "//pw_interrupt_freertos:docs",
        "//pw_interrupt_zephyr:docs",
        "//pw_intrusive_ptr:docs",
        "//pw_json:docs",
        "//pw_kernel:docs",
        "//pw_kvs:docs",
        "//pw_libc:docs",
        "//pw_libcxx:docs",
        "//pw_log:docs",
        "//pw_log_android:docs",
        "//pw_log_basic:docs",
        "//pw_log_fuchsia:docs",
        "//pw_log_null:docs",
        "//pw_log_rpc:docs",
        "//pw_log_string:docs",
        "//pw_log_tokenized:docs",
        "//pw_log_zephyr:docs",
        "//pw_malloc:docs",
        "//pw_malloc_freelist:docs",
        "//pw_malloc_freertos:docs",
        "//pw_memory:docs",
        "//pw_metric:docs",
        "//pw_module:docs",
        "//pw_multibuf:docs",
        "//pw_multisink:docs",
        "//pw_numeric:docs",
        "//pw_package:docs",
        "//pw_perf_test:docs",
        "//pw_persistent_ram:docs",
        "//pw_polyfill:docs",
        "//pw_preprocessor:docs",
        "//pw_presubmit:docs",
        "//pw_protobuf:docs",
        "//pw_protobuf_compiler:docs",
        "//pw_random:docs",
        "//pw_random_fuchsia:docs",
        "//pw_result:docs",
        "//pw_ring_buffer:docs",
        "//pw_router:docs",
        "//pw_rpc:docs",
        "//pw_rpc_transport:docs",
        "//pw_rust:sphinx",
        "//pw_sensor:docs",
        "//pw_snapshot:docs",
        "//pw_software_update:docs",
        "//pw_span:docs",
        "//pw_spi:docs",
        "//pw_spi_linux:docs",
        "//pw_spi_mcuxpresso:docs",
        "//pw_spi_rp2040:docs",
        "//pw_spi_zephyr:docs",
        "//pw_status:docs",
        "//pw_stm32cube_build:docs",
        "//pw_stream:docs",
        "//pw_stream_uart_linux:docs",
        "//pw_stream_uart_mcuxpresso:docs",
        "//pw_string:docs",
        "//pw_symbolizer:docs",
        "//pw_sync:docs",
        "//pw_sync_baremetal:docs",
        "//pw_sync_embos:docs",
        "//pw_sync_freertos:docs",
        "//pw_sync_stl:docs",
        "//pw_sync_threadx:docs",
        "//pw_sync_zephyr:docs",
        "//pw_sys_io:docs",
        "//pw_sys_io_ambiq_sdk:docs",
        "//pw_sys_io_arduino:docs",
        "//pw_sys_io_baremetal_lm3s6965evb:docs",
        "//pw_sys_io_baremetal_stm32f429:docs",
        "//pw_sys_io_emcraft_sf2:docs",
        "//pw_sys_io_mcuxpresso:docs",
        "//pw_sys_io_rp2040:docs",
        "//pw_sys_io_stdio:docs",
        "//pw_sys_io_stm32cube:docs",
        "//pw_sys_io_zephyr:docs",
        "//pw_system:docs",
        "//pw_target_runner:docs",
        "//pw_thread:docs",
        "//pw_thread_embos:docs",
        "//pw_thread_freertos:docs",
        "//pw_thread_stl:docs",
        "//pw_thread_threadx:docs",
        "//pw_thread_zephyr:docs",
        "//pw_time:docs",
        "//pw_tls_client:docs",
        "//pw_tls_client_boringssl:docs",
        "//pw_tls_client_mbedtls:docs",
        "//pw_tokenizer:docs",
        "//pw_toolchain:docs",
        "//pw_trace:docs",
        "//pw_trace_tokenized:docs",
        "//pw_transfer:docs",
        "//pw_uart:docs",
        "//pw_uart_mcuxpresso:docs",
        "//pw_unit_test:docs",
        "//pw_uuid:docs",
        "//pw_varint:docs",
        "//pw_watch:docs",
        "//pw_web:docs",
        "//pw_work_queue:docs",
        # end (sentinel for pw module create)
        "//seed:docs",
        "//targets:docs",
        "//third_party:docs",
    ],
    target_compatible_with = incompatible_with_mcu(),
    visibility = ["//visibility:private"],
)

sphinx_build_binary(
    name = "sphinx_build",
    tags = [
        "manual",
        "nomypy",
    ],
    target_compatible_with = incompatible_with_mcu(),
    visibility = ["//visibility:private"],
    deps = [
        "//pw_build/py:pigweed_build",
        "//pw_build/py:pw_build",
        "//pw_build/py:pw_project_builder",
        "//pw_bytes/py:pw_bytes",
        "//pw_console/py:pw_console",
        "//pw_containers/py:inline_var_len_entry_queue",
        "//pw_docgen/py:pw_docgen",
        "//pw_elf/py:pw_elf",
        "//pw_emu/py:pw_emu",
        "//pw_env_setup/py:pw_env_setup",
        "//pw_env_setup/py:pw_env_setup_private",
        "//pw_hdlc/py:pw_hdlc",
        "//pw_ide/py:pw_ide",
        "//pw_log/py:pw_log",
        "//pw_log_rpc/py:pw_log_rpc",
        "//pw_presubmit/py:pw_presubmit",
        "//pw_protobuf_compiler/py:pw_protobuf_compiler",
        "//pw_rpc/py:pw_rpc_benchmark",
        "//pw_status/py:pw_status",
        "//pw_system/py:device_sim",
        "//pw_system/py:pw_system_benchmark_runner",
        "//pw_system/py:pw_system_console",
        "//pw_system/py:pw_system_lib",
        "//pw_tokenizer/py:pw_tokenizer",
        "//pw_transfer/py:pw_transfer",
        "//pw_unit_test/py:pw_unit_test",
        "//pw_watch/py:pw_watch",
        "//pw_watch/py:watch",
        "@pigweed_doxylink",
        "@pigweed_python_packages//jsonschema",
        "@pigweed_python_packages//pydata_sphinx_theme",
        "@pigweed_python_packages//pytz",
        "@pigweed_python_packages//sphinx",
        "@pigweed_python_packages//sphinx_argparse",
        "@pigweed_python_packages//sphinx_copybutton",
        "@pigweed_python_packages//sphinx_design",
        "@pigweed_python_packages//sphinx_reredirects",
        "@pigweed_python_packages//sphinxcontrib_mermaid",
        "@rules_python//python/runfiles",
    ],
)

# Use Sphinx to build the main pigweed.dev website.
#
# The main `docs` target must output a directory containing the fully
# built pigweed.dev website. It must output a directory, not an archive,
# because our deploy code expects a directory when it uploads the website
# code and assets to our CDN.
sphinx_docs(
    name = "docs",
    # Persistent worker dramatically speeds up iterative docs builds. Tradeoff
    # is that the docs build becomes non-hermetic. If Sphinx is failing at
    # `Ignored unreadable document` it means you're having non-hermetic caching
    # issues. Set `allow_persistent_workers` to `False`, re-run the docs build
    # (this one will be longer because it's a hermetic build), and then set it
    # back to `True` to get faster iterative builds.
    # https://github.com/bazel-contrib/rules_python/pull/2938
    allow_persistent_workers = False,
    config = "conf.py",
    extra_opts = [
        # Do not use `--silent` option because `--fail-on-warning`
        # does not seem to work as expected with `--silent`.
        "--quiet",
        "--fail-on-warning",
        "--jobs",
        "16",
    ],
    formats = [
        "html",
    ],
    sphinx = ":sphinx_build",
    strip_prefix = "docs/sphinx/",
    tags = ["manual"],
    target_compatible_with = incompatible_with_mcu(),
    visibility = ["//visibility:public"],
    deps = [
        ":content",
        ":extensions",
        ":rust",
        ":static",
        "//docs/doxygen:html",
        "//docs/doxygen:xml",
    ],
)