docs/BUILD.bazel

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

package(default_visibility = ["//visibility:public"])

licenses(["notice"])

exports_files([
    "module_metadata.json",
    "module_metadata_schema.json",
])

sphinx_docs_library(
    # TODO: https://pwbug.dev/377679855 - Rename this to "docs" after merging.
    name = "not_prefixed",
    srcs = [
        "_extensions/bug.py",
        "_extensions/sitemap.py",
        "automated_analysis.rst",
        "bazel_compatibility.rst",
        "build_system.rst",
        "changelog.rst",
        "index.rst",
        "module_metadata.json",
        "module_metadata_schema.json",
        "modules.rst",
        "python_build.rst",
        "targets.rst",
        "third_party_support.rst",
        "toolchain.rst",
    ],
    strip_prefix = "docs/",
    target_compatible_with = incompatible_with_mcu(),
)

# TODO: https://pwbug.dev/377679855 - Merge this into "not_prefixed"
# (which will be renamed to "docs" after the merge).
sphinx_docs_library(
    name = "prefixed",
    srcs = [
        "_static/css/pigweed.css",
        "_static/js/changelog.js",
        "_static/js/pigweed.js",
        "3p/index.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/index.rst",
        "blog/rss.xml",
        "code_of_conduct.rst",
        "code_reviews.rst",
        "community/index.rst",
        "concepts/index.rst",
        "contributing/index.rst",
        "contributing/docs/changelog.rst",
        "contributing/docs/guides.rst",
        "contributing/docs/index.rst",
        "contributing/docs/modules.rst",
        "embedded_cpp_guide.rst",
        "facades.rst",
        "faq.rst",
        "get_started/bazel_integration.rst",
        "get_started/bazel.rst",
        "get_started/first_time_setup.rst",
        "get_started/github_actions.rst",
        "get_started/index.rst",
        "get_started/install_bazel.rst",
        "get_started/upstream.rst",
        "get_started/zephyr.rst",
        "glossary.rst",
        "infra/bazel_lockfile.rst",
        "infra/ci_cq_intro.rst",
        "infra/index.rst",
        "infra/rollers.rst",
        "layout/layout.html",
        "mission.rst",
        "module_structure.rst",
        "os/index.rst",
        "os/zephyr/index.rst",
        # TODO: https://pwbug.dev/377683258 - Enable this file after
        # https://pwrev.dev/248014 merges.
        # "os/zephyr/kconfig.rst",
        "overview.rst",
        "showcases/index.rst",
        "showcases/sense/index.rst",
        "showcases/sense/tutorial/automate.rst",
        "showcases/sense/tutorial/bazel_cloud.rst",
        "showcases/sense/tutorial/build.rst",
        "showcases/sense/tutorial/code_intelligence.rst",
        "showcases/sense/tutorial/crash_handler.rst",
        "showcases/sense/tutorial/device_tests.rst",
        "showcases/sense/tutorial/explore.rst",
        "showcases/sense/tutorial/factory.rst",
        "showcases/sense/tutorial/flash.rst",
        "showcases/sense/tutorial/host_sim.rst",
        "showcases/sense/tutorial/host_tests.rst",
        "showcases/sense/tutorial/index.rst",
        "showcases/sense/tutorial/outro.rst",
        "showcases/sense/tutorial/production.rst",
        "showcases/sense/tutorial/rpc.rst",
        "showcases/sense/tutorial/setup.rst",
        "showcases/sense/tutorial/web.rst",
        "size_optimizations.rst",
        "style/cli.rst",
        "style/commit_message.rst",
        "style/cpp.rst",
        "style/doxygen.rst",
        "style/protobuf.rst",
        "style/rest.rst",
        "style/writing.rst",
        "style_guide.rst",
    ],
    # TODO: https://pwbug.dev/377679855 - Remove this URL prefix.
    prefix = "docs/",
    target_compatible_with = incompatible_with_mcu(),
)

copy_directory(
    name = "rust_files",
    src = "//pw_rust:docs_dir",
    out = "rustdoc",
)

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

filegroup(
    name = "doxygen_srcs",
    srcs = [
        "//pw_alignment:doxygen",
        "//pw_allocator:doxygen",
        "//pw_analog:doxygen",
        "//pw_async:doxygen",
        "//pw_async2:doxygen",
        "//pw_async2_basic:doxygen",
        "//pw_async_basic:doxygen",
        "//pw_base64:doxygen",
        "//pw_bluetooth:doxygen",
        "//pw_bluetooth_proxy:doxygen",
        "//pw_build:doxygen",
        "//pw_bytes:doxygen",
        "//pw_channel:doxygen",
        "//pw_chre:doxygen",
        "//pw_chrono:doxygen",
        "//pw_clock_tree:doxygen",
        "//pw_clock_tree_mcuxpresso:doxygen",
        "//pw_containers:doxygen",
        "//pw_crypto:doxygen",
        "//pw_digital_io:doxygen",
        "//pw_display:doxygen",
        "//pw_elf:doxygen",
        "//pw_function:doxygen",
        "//pw_hdlc:doxygen",
        "//pw_hex_dump:doxygen",
        "//pw_i2c:doxygen",
        "//pw_i2c_linux:doxygen",
        "//pw_interrupt:doxygen",
        "//pw_json:doxygen",
        "//pw_kvs:doxygen",
        "//pw_log:doxygen",
        "//pw_log_string:doxygen",
        "//pw_log_tokenized:doxygen",
        "//pw_malloc:doxygen",
        "//pw_multibuf:doxygen",
        "//pw_numeric:doxygen",
        "//pw_perf_test:doxygen",
        "//pw_polyfill:doxygen",
        "//pw_preprocessor:doxygen",
        "//pw_protobuf:doxygen",
        "//pw_random:doxygen",
        "//pw_rpc:doxygen",
        "//pw_span:doxygen",
        "//pw_spi:doxygen",
        "//pw_status:doxygen",
        "//pw_stream:doxygen",
        "//pw_stream_uart_linux:doxygen",
        "//pw_string:doxygen",
        "//pw_sync:doxygen",
        "//pw_sys_io:doxygen",
        "//pw_system:doxygen",
        "//pw_thread:doxygen",
        "//pw_tokenizer:doxygen",
        "//pw_toolchain:doxygen",
        "//pw_transfer:doxygen",
        "//pw_uart:doxygen",
        "//pw_unit_test:doxygen",
        "//pw_varint:doxygen",
        "//pw_work_queue:doxygen",
    ],
)

# Run Doxygen on the gathered headers to generate XML.
doxygen(
    name = "doxygen_build",
    srcs = [
        ":doxygen_srcs",
    ],
    outs = [
        "xml",
    ],
    # TODO: b/384047922 - Move configuration to a dedicated Doxyfile.
    configurations = [
        # Use `leading-asterisk` even though `leading-slashes` is more
        # semantically accurate (all Doxygen comments in Pigweed codebase
        # start with `///`). See the discussion about undocumented Doxygen
        # behavior at the bottom of this section:
        # https://breathe.readthedocs.io/en/latest/markups.html#aliases
        "ALIASES = \"rst=^^@verbatim embed:rst:leading-asterisk^^\"",
        "ALIASES += \"endrst=@endverbatim\"",
        "ALIASES += \"rstref{1}=@verbatim embed:rst:inline :ref:`\\1` @endverbatim\"",
        "ALIASES += \"crossref{3}=@verbatim embed:rst:inline :\\1:\\2:`\\3` @endverbatim\"",
        "ALIASES += \"c_macro{1}=@crossref{c,macro,\\1}\"",
        "ALIASES += \"cpp_class{1}=@crossref{cpp,class,\\1}\"",
        "ALIASES += \"cpp_func{1}=@crossref{cpp,func,\\1}\"",
        "ALIASES += \"cpp_type{1}=@crossref{cpp,type,\\1}\"",
        "ALIASES += \"cpp_enum{1}=@crossref{cpp,type,\\1}\"",
        "ALIASES += \"pw_status{1}=@crossref{c,enumerator,\\1}\"",
        "CASE_SENSE_NAMES = NO",
        "ENABLE_PREPROCESSING = YES",
        "EXTRACT_PACKAGE = YES",
        "EXTRACT_PRIV_VIRTUAL = YES",
        "EXTRACT_STATIC = YES",
        "GENERATE_HTML = NO",
        "GENERATE_XML = YES",
        "INCLUDE_GRAPH = NO",
        "MACRO_EXPANSION = YES",
        "PROJECT_NAME = Pigweed",
        """PREDEFINED = __cplusplus=202002L \\
                        PW_LOCKABLE= \\
                        PW_PRINTF_FORMAT(...)= \\
                        PW_CONSTEXPR_CPP20= \\
                        PW_EXCLUSIVE_LOCK_FUNCTION(...)= \\
                        PW_EXCLUSIVE_TRYLOCK_FUNCTION(...)= \\
                        PW_UNLOCK_FUNCTION(...)= \\
                        PW_NO_LOCK_SAFETY_ANALYSIS= \\
                        PW_CXX_STANDARD_IS_SUPPORTED(...)=1 \\
                        PW_EXTERN_C_START= \\
                        PW_LOCKS_EXCLUDED(...)= \\
                        PW_EXCLUSIVE_LOCKS_REQUIRED(...)= \\
                        PW_GUARDED_BY(...)= \\
                        PW_NO_SANITIZE(...)= \\
                        PW_NODISCARD_STR(...)= \\
                        configSUPPORT_STATIC_ALLOCATION=1 \\
                        configUSE_TIMERS=1 \\
                        configCHECK_FOR_STACK_OVERFLOW=1 \\
                        PW_EXCLUDE_FROM_DOXYGEN=1""",
        "RECURSIVE = YES",
    ],
    # Don't use rules_doxygen's `aliases` attribute. Define aliases within
    # `configurations`. The `aliases` attribute doesn't render aliases with
    # args correctly: https://github.com/TendTo/rules_doxygen/issues/12
    # aliases = []
    target_compatible_with = incompatible_with_mcu(),
)

# Package up the Doxygen-generated XML in a way that's easy for
# Breathe/Sphinx to consume.
sphinx_docs_library(
    name = "doxygen_xml",
    srcs = [":doxygen_build"],
    prefix = "doxygen/",
    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//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",
    config = "conf.py",
    formats = [
        "html",
    ],
    sphinx = ":sphinx_build",
    strip_prefix = "docs/",
    target_compatible_with = incompatible_with_mcu(),
    deps = [
        ":doxygen_xml",
        ":not_prefixed",
        ":prefixed",
        # TODO: https://pwbug.dev/383540117 - Move this comment to a dedicated
        # contributor's guide on the Bazel docgen system.
        #
        # The fully built rustdoc subsite is provided as a dependency
        # here. The `html_extra_path` config in `//docs/conf.py` instructs Sphinx
        # to copy the rustdoc directory to its output.
        #
        # Having rustdoc be a dependency to Sphinx probably reduces parallelism of
        # the docs site build but was the only solution that worked and has a few
        # advantages:
        #
        # * When previewing the docs site locally, rustdoc links now work.
        #   I.e. after running `bazelisk run //docs:docs.serve` you can browse
        #   both the main Sphinx site and the rustdoc subsite.
        #
        # * Automation related to the rustdoc subsite is now easier. E.g. we
        #   can now use Sphinx's built-in link checker to make sure that
        #   there are no 404ing rustdoc links.
        #
        # * The main Sphinx site and rustdoc subsite can be deployed in 1 step.
        ":rust",
        "//pw_alignment:docs",
        "//pw_allocator: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_async2_basic:docs",
        "//pw_async2_epoll:docs",
        "//pw_async_basic:docs",
        "//pw_async_fuchsia: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_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_display:docs",
        "//pw_dma_mcuxpresso:docs",
        "//pw_docgen:docs",
        "//pw_doctor:docs",
        "//pw_elf:docs",
        "//pw_emu:docs",
        "//pw_env_setup:docs",
        "//pw_env_setup_zephyr:docs",
        "//pw_file:docs",
        "//pw_format: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_ide:docs",
        "//pw_interrupt:docs",
        "//pw_interrupt_cortex_m:docs",
        "//pw_interrupt_xtensa:docs",
        "//pw_interrupt_zephyr:docs",
        "//pw_intrusive_ptr:docs",
        "//pw_json: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_metric:docs",
        "//pw_minimal_cpp_stdlib: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_status:docs",
        "//pw_stm32cube_build:docs",
        "//pw_stream:docs",
        "//pw_stream_shmem_mcuxpresso: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_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_unit_test_zephyr:docs",
        "//pw_varint:docs",
        "//pw_watch:docs",
        "//pw_web:docs",
        "//pw_work_queue:docs",
        "//seed:docs",
        "//targets:docs",
        "//:docs",
    ],
)