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

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 = [
        "automated_analysis.rst",
        "bazel_compatibility.rst",
        "build_system.rst",
        "changelog.rst",
        "index.rst",
        "layout/layout.html",
        "module_metadata.json",
        "module_metadata_schema.json",
        "modules.rst",
        "python_build.rst",
        "targets.rst",
        "third_party_support.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",
        "_static/pw_logo.ico",
        "_static/pw_logo.svg",
        "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/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/ci_cq_intro.rst",
        "infra/index.rst",
        "infra/rollers.rst",
        "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/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(),
)

sphinx_docs(
    name = "docs",
    config = "conf.py",
    formats = [
        "html",
    ],
    sphinx = ":sphinx-build",
    strip_prefix = "docs/",
    target_compatible_with = incompatible_with_mcu(),
    deps = [
        ":not_prefixed",
        ":prefixed",
        "//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",
        # TODO: https://pwbug.dev/378570156 - Enable after Doxygen lands.
        # "//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_emu:docs",
        "//pw_env_setup:docs",
        "//pw_env_setup_zephyr:docs",
        "//pw_file:docs",
        "//pw_format:docs",
        # TODO: https://pwbug.dev/378570156 - Enable after Doxygen lands.
        # "//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",
        # TODO: https://pwbug.dev/378570156 - Enable after Doxygen lands.
        # "//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",
        # TODO: https://pwbug.dev/378570156 - Enable after Doxygen lands.
        # "//pw_polyfill:docs",
        "//pw_preprocessor:docs",
        "//pw_presubmit:docs",
        # TODO: https://pwbug.dev/378570156 - Enable after Doxygen lands.
        # "//pw_protobuf:docs",
        "//pw_protobuf_compiler:docs",
        "//pw_random:docs",
        "//pw_random_fuchsia:docs",
        "//pw_result:docs",
        "//pw_ring_buffer:docs",
        "//pw_router:docs",
        # TODO: https://pwbug.dev/378570156 - Enable after Doxygen lands.
        # "//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",
        # TODO: https://pwbug.dev/378570156 - Enable after Doxygen lands.
        # "//pw_string:docs",
        "//pw_symbolizer:docs",
        # TODO: https://pwbug.dev/378570156 - Enable after Doxygen lands.
        # "//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",
        # TODO: https://pwbug.dev/378570156 - Enable after Doxygen lands.
        # "//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",
        # TODO: https://pwbug.dev/378570156 - Enable after Doxygen lands.
        # "//pw_tokenizer:docs",
        "//pw_toolchain:docs",
        "//pw_trace:docs",
        "//pw_trace_tokenized:docs",
        "//pw_transfer:docs",
        "//pw_uart:docs",
        "//pw_uart_mcuxpresso:docs",
        # TODO: https://pwbug.dev/378765499 - Update downstream projects.
        # "//pw_unit_test:docs",
        "//pw_unit_test_zephyr:docs",
        # TODO: https://pwbug.dev/378570156 - Enable after Doxygen lands.
        # "//pw_varint:docs",
        "//pw_watch:docs",
        "//pw_web:docs",
        "//pw_work_queue:docs",
        "//seed:docs",
        "//targets:docs",
        "//:docs",
    ],
)

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",
    ],
)

filegroup(
    name = "doxygen",
    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",
    ],
)