docs/BUILD.gn

# Copyright 2019 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.

import("//build_overrides/pigweed.gni")

import("$dir_pw_build/python.gni")
import("$dir_pw_build/python_action.gni")
import("$dir_pw_docgen/docs.gni")

pw_doc_group("static_assets") {
  inputs = [
    "_static/css/pigweed.css",
    "_static/js/changelog.js",
    "_static/js/pigweed.js",
    "_static/pw_logo.ico",
    "_static/pw_logo.svg",
  ]
}

# Note: These may be useful for downstream projects, which is why they are
# split out from the overall docgen target below.
pw_doc_group("core_docs") {
  inputs = [
    "$dir_pw_build/py/gn_tests/BUILD.gn",
    "$dir_pw_build/py/pw_build/generate_python_wheel_cache.py",
    "$dir_pw_build/python.gni",
    "$dir_pw_build/python_gn_args.gni",
    "layout/page.html",
    "run_doxygen.py",
  ]
  sources = [
    "blog/01-kudzu.rst",
    "blog/index.rst",
    "code_of_conduct.rst",
    "code_reviews.rst",
    "concepts/index.rst",
    "contributing/changelog.rst",
    "contributing/index.rst",
    "contributing/module_docs.rst",
    "editors.rst",
    "embedded_cpp_guide.rst",
    "facades.rst",
    "faq.rst",
    "get_started/bazel.rst",
    "get_started/bazel_integration.rst",
    "get_started/first_time_setup.rst",
    "get_started/index.rst",
    "get_started/upstream.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",
    "os/zephyr/kconfig.rst",
    "overview.rst",
    "size_optimizations.rst",
    "style/commit_message.rst",
    "style/cpp.rst",
    "style/doxygen.rst",
    "style/protobuf.rst",
    "style/sphinx.rst",
    "style_guide.rst",
  ]
}

# Documentation for upstream Pigweed targets.
group("target_docs") {
  deps = [
    "$dir_pigweed/targets/android:target_docs",
    "$dir_pigweed/targets/apollo4:target_docs",
    "$dir_pigweed/targets/apollo4_pw_system:target_docs",
    "$dir_pigweed/targets/arduino:target_docs",
    "$dir_pigweed/targets/docs:target_docs",
    "$dir_pigweed/targets/emcraft_sf2_som:docs",
    "$dir_pigweed/targets/host:target_docs",
    "$dir_pigweed/targets/host_device_simulator:target_docs",
    "$dir_pigweed/targets/lm3s6965evb_qemu:target_docs",
    "$dir_pigweed/targets/mimxrt595_evk:target_docs",
    "$dir_pigweed/targets/rp2040:target_docs",
    "$dir_pigweed/targets/stm32f429i_disc1:target_docs",
    "$dir_pigweed/targets/stm32f429i_disc1_stm32cube:target_docs",
  ]
}

group("module_docs") {
  deps = pw_module_docs
}

group("third_party_docs") {
  deps = [
    "$dir_pigweed/third_party/abseil-cpp:docs",
    "$dir_pigweed/third_party/boringssl:docs",
    "$dir_pigweed/third_party/emboss:docs",
    "$dir_pigweed/third_party/freertos:docs",
    "$dir_pigweed/third_party/fuchsia:docs",
    "$dir_pigweed/third_party/fuzztest:docs",
    "$dir_pigweed/third_party/googletest:docs",
    "$dir_pigweed/third_party/nanopb:docs",
    "$dir_pigweed/third_party/re2:docs",
    "$dir_pigweed/third_party/tinyusb:docs",
  ]
}

# All sources with doxygen comment blocks.
_doxygen_input_files = [  # keep-sorted: start
  "$dir_pw_alignment/public/pw_alignment/alignment.h",
  "$dir_pw_allocator/public/pw_allocator/allocator.h",
  "$dir_pw_allocator/public/pw_allocator/block.h",
  "$dir_pw_allocator/public/pw_allocator/block_allocator.h",
  "$dir_pw_allocator/public/pw_allocator/buffer.h",
  "$dir_pw_allocator/public/pw_allocator/fallback_allocator.h",
  "$dir_pw_allocator/public/pw_allocator/fuzzing.h",
  "$dir_pw_allocator/public/pw_allocator/libc_allocator.h",
  "$dir_pw_allocator/public/pw_allocator/metrics.h",
  "$dir_pw_allocator/public/pw_allocator/null_allocator.h",
  "$dir_pw_allocator/public/pw_allocator/size_reporter.h",
  "$dir_pw_allocator/public/pw_allocator/synchronized_allocator.h",
  "$dir_pw_allocator/public/pw_allocator/test_harness.h",
  "$dir_pw_allocator/public/pw_allocator/testing.h",
  "$dir_pw_allocator/public/pw_allocator/tracking_allocator.h",
  "$dir_pw_analog/public/pw_analog/analog_input.h",
  "$dir_pw_analog/public/pw_analog/microvolt_input.h",
  "$dir_pw_async/public/pw_async/context.h",
  "$dir_pw_async/public/pw_async/dispatcher.h",
  "$dir_pw_async/public/pw_async/fake_dispatcher_fixture.h",
  "$dir_pw_async/public/pw_async/function_dispatcher.h",
  "$dir_pw_async/public/pw_async/heap_dispatcher.h",
  "$dir_pw_async/public/pw_async/task.h",
  "$dir_pw_async/public/pw_async/task_function.h",
  "$dir_pw_async2/public/pw_async2/dispatcher.h",
  "$dir_pw_async2/public/pw_async2/dispatcher_base.h",
  "$dir_pw_async2/public/pw_async2/poll.h",
  "$dir_pw_async2_basic/public_overrides/pw_async2/dispatcher_native.h",
  "$dir_pw_async_basic/public/pw_async_basic/dispatcher.h",
  "$dir_pw_base64/public/pw_base64/base64.h",
  "$dir_pw_bluetooth/public/pw_bluetooth/gatt/client.h",
  "$dir_pw_bluetooth/public/pw_bluetooth/gatt/server.h",
  "$dir_pw_bluetooth/public/pw_bluetooth/host.h",
  "$dir_pw_bluetooth/public/pw_bluetooth/low_energy/central.h",
  "$dir_pw_bluetooth/public/pw_bluetooth/low_energy/connection.h",
  "$dir_pw_bluetooth/public/pw_bluetooth/low_energy/peripheral.h",
  "$dir_pw_bytes/public/pw_bytes/bit.h",
  "$dir_pw_bytes/public/pw_bytes/byte_builder.h",
  "$dir_pw_channel/public/pw_channel/channel.h",
  "$dir_pw_chre/public/pw_chre/chre.h",
  "$dir_pw_chre/public/pw_chre/host_link.h",
  "$dir_pw_chrono/public/pw_chrono/system_clock.h",
  "$dir_pw_chrono/public/pw_chrono/system_timer.h",
  "$dir_pw_containers/public/pw_containers/filtered_view.h",
  "$dir_pw_containers/public/pw_containers/inline_deque.h",
  "$dir_pw_containers/public/pw_containers/inline_queue.h",
  "$dir_pw_containers/public/pw_containers/inline_var_len_entry_queue.h",
  "$dir_pw_crypto/public/pw_crypto/ecdsa.h",
  "$dir_pw_crypto/public/pw_crypto/sha256.h",
  "$dir_pw_digital_io/public/pw_digital_io/digital_io.h",
  "$dir_pw_function/public/pw_function/function.h",
  "$dir_pw_function/public/pw_function/pointer.h",
  "$dir_pw_function/public/pw_function/scope_guard.h",
  "$dir_pw_hdlc/public/pw_hdlc/decoder.h",
  "$dir_pw_hdlc/public/pw_hdlc/encoder.h",
  "$dir_pw_i2c/public/pw_i2c/initiator.h",
  "$dir_pw_i2c/public/pw_i2c/register_device.h",
  "$dir_pw_i2c_linux/public/pw_i2c_linux/initiator.h",
  "$dir_pw_interrupt/public/pw_interrupt/context.h",
  "$dir_pw_json/public/pw_json/builder.h",
  "$dir_pw_kvs/public/pw_kvs/key_value_store.h",
  "$dir_pw_kvs/pw_kvs_private/config.h",
  "$dir_pw_log/public/pw_log/tokenized_args.h",
  "$dir_pw_log_string/public/pw_log_string/handler.h",
  "$dir_pw_log_tokenized/public/pw_log_tokenized/base64.h",
  "$dir_pw_log_tokenized/public/pw_log_tokenized/handler.h",
  "$dir_pw_log_tokenized/public/pw_log_tokenized/metadata.h",
  "$dir_pw_multibuf/public/pw_multibuf/allocator.h",
  "$dir_pw_multibuf/public/pw_multibuf/chunk.h",
  "$dir_pw_multibuf/public/pw_multibuf/header_chunk_region_tracker.h",
  "$dir_pw_multibuf/public/pw_multibuf/multibuf.h",
  "$dir_pw_multibuf/public/pw_multibuf/simple_allocator.h",
  "$dir_pw_multibuf/public/pw_multibuf/single_chunk_region_tracker.h",
  "$dir_pw_perf_test/public/pw_perf_test/event_handler.h",
  "$dir_pw_perf_test/public/pw_perf_test/perf_test.h",
  "$dir_pw_polyfill/public/pw_polyfill/language_feature_macros.h",
  "$dir_pw_polyfill/public/pw_polyfill/standard.h",
  "$dir_pw_preprocessor/public/pw_preprocessor/compiler.h",
  "$dir_pw_protobuf/public/pw_protobuf/find.h",
  "$dir_pw_random/public/pw_random/random.h",
  "$dir_pw_random/public/pw_random/xor_shift.h",
  "$dir_pw_rpc/public/pw_rpc/internal/config.h",
  "$dir_pw_rpc/public/pw_rpc/synchronous_call.h",
  "$dir_pw_span/public/pw_span/internal/config.h",
  "$dir_pw_spi/public/pw_spi/chip_selector.h",
  "$dir_pw_spi/public/pw_spi/chip_selector_digital_out.h",
  "$dir_pw_status/public/pw_status/status.h",
  "$dir_pw_stream/public/pw_stream/stream.h",
  "$dir_pw_stream_uart_linux/public/pw_stream_uart_linux/stream.h",
  "$dir_pw_string/public/pw_string/format.h",
  "$dir_pw_string/public/pw_string/string.h",
  "$dir_pw_string/public/pw_string/string_builder.h",
  "$dir_pw_string/public/pw_string/util.h",
  "$dir_pw_sync/public/pw_sync/binary_semaphore.h",
  "$dir_pw_sync/public/pw_sync/borrow.h",
  "$dir_pw_sync/public/pw_sync/counting_semaphore.h",
  "$dir_pw_sync/public/pw_sync/inline_borrowable.h",
  "$dir_pw_sync/public/pw_sync/interrupt_spin_lock.h",
  "$dir_pw_sync/public/pw_sync/lock_annotations.h",
  "$dir_pw_sync/public/pw_sync/mutex.h",
  "$dir_pw_sync/public/pw_sync/thread_notification.h",
  "$dir_pw_sync/public/pw_sync/timed_mutex.h",
  "$dir_pw_sync/public/pw_sync/timed_thread_notification.h",
  "$dir_pw_sync/public/pw_sync/virtual_basic_lockable.h",
  "$dir_pw_sys_io/public/pw_sys_io/sys_io.h",
  "$dir_pw_thread/public/pw_thread/test_thread_context.h",
  "$dir_pw_tokenizer/public/pw_tokenizer/config.h",
  "$dir_pw_tokenizer/public/pw_tokenizer/encode_args.h",
  "$dir_pw_tokenizer/public/pw_tokenizer/nested_tokenization.h",
  "$dir_pw_tokenizer/public/pw_tokenizer/token_database.h",
  "$dir_pw_tokenizer/public/pw_tokenizer/tokenize.h",
  "$dir_pw_toolchain/public/pw_toolchain/no_destructor.h",
  "$dir_pw_transfer/public/pw_transfer/atomic_file_transfer_handler.h",
  "$dir_pw_unit_test/light_public_overrides/pw_unit_test/framework_backend.h",
  "$dir_pw_unit_test/public/pw_unit_test/config.h",
  "$dir_pw_unit_test/public/pw_unit_test/event_handler.h",
  "$dir_pw_unit_test/public/pw_unit_test/googletest_handler_adapter.h",
  "$dir_pw_unit_test/public/pw_unit_test/googletest_style_event_handler.h",
  "$dir_pw_unit_test/public/pw_unit_test/logging_event_handler.h",
  "$dir_pw_unit_test/public/pw_unit_test/multi_event_handler.h",
  "$dir_pw_unit_test/public/pw_unit_test/printf_event_handler.h",
  "$dir_pw_unit_test/public/pw_unit_test/simple_printing_event_handler.h",
  "$dir_pw_unit_test/public/pw_unit_test/static_library_support.h",
  "$dir_pw_varint/public/pw_varint/stream.h",
  "$dir_pw_varint/public/pw_varint/varint.h",
  "$dir_pw_work_queue/public/pw_work_queue/work_queue.h",
]  # keep-sorted: end

pw_python_action("generate_doxygen") {
  _output_dir = "docs/doxygen"
  script = "run_doxygen.py"
  inputs = [
    "//PIGWEED_MODULES",
    "Doxyfile",
  ]
  inputs += _doxygen_input_files
  args = [
    "--gn-root",
    rebase_path("//", root_build_dir),
    "--pigweed-modules-file",
    rebase_path("//PIGWEED_MODULES", root_build_dir),
    "--output-dir",
    _output_dir,
    "--doxygen-config",
    rebase_path("Doxyfile", root_build_dir),
    "--include-paths",
  ]
  args += rebase_path(_doxygen_input_files, root_build_dir)
  outputs = [ "$root_build_dir/$_output_dir/xml/index.xml" ]
}

pw_doc_gen("docs") {
  conf = "conf.py"
  sources = [
    # Note: These must use the "docs" prefix for links and image references. In
    # contrast, the pw_doc_group above should not use the docs prefix.
    "automated_analysis.rst",
    "build_system.rst",
    "changelog.rst",
    "index.rst",
    "modules.rst",
    "python_build.rst",
    "targets.rst",
    "third_party_support.rst",
  ]
  output_directory = target_gen_dir
  deps = [
    ":core_docs",
    ":generate_doxygen",
    ":module_docs",
    ":static_assets",
    ":target_docs",
    ":third_party_docs",
    "$dir_pigweed/kudzu:docs",
    "$dir_pigweed/seed:seeds",
    "$dir_pw_env_setup:python.install",
  ]

  # Required to set the PYTHONPATH so automodule, autoclass or autofunction RST
  # directives work.
  python_metadata_deps = [ "$dir_pw_env_setup:core_pigweed_python_packages" ]
}