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/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/python.gni",
    "images/pw_env_setup_demo.gif",
    "images/pw_status_test.png",
    "images/pw_watch_build_demo.gif",
    "images/pw_watch_on_device_demo.gif",
    "images/pw_watch_test_demo.gif",
    "images/pw_watch_test_demo2.gif",
    "images/stm32f429i-disc1_connected.jpg",
    "run_doxygen.py",
  ]
  sources = [
    "code_of_conduct.rst",
    "concepts/index.rst",
    "contributing.rst",
    "embedded_cpp_guide.rst",
    "faq.rst",
    "getting_started.rst",
    "module_structure.rst",
    "os/index.rst",
    "os/zephyr.rst",
    "size_optimizations.rst",
    "style_guide.rst",
  ]
}

pw_doc_group("release_notes") {
  sources = [
    "release_notes/2022_jan.rst",
    "release_notes/index.rst",
  ]
}

pw_doc_group("templates") {
  sources = [
    "templates/docs/api.rst",
    "templates/docs/cli.rst",
    "templates/docs/concepts.rst",
    "templates/docs/design.rst",
    "templates/docs/docs.rst",
    "templates/docs/gui.rst",
    "templates/docs/guides.rst",
    "templates/docs/tutorials/index.rst",
  ]
}

# Documentation for upstream Pigweed targets.
group("target_docs") {
  deps = [
    "$dir_pigweed/targets/android: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/rp2040_pw_system: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",
  ]
}

_doxygen_input_files = [
  # All sources with doxygen comment blocks.
  "$dir_pw_allocator/public/pw_allocator/block.h",
  "$dir_pw_async/public/pw_async/dispatcher.h",
  "$dir_pw_async/public/pw_async/heap_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/task.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_containers/public/pw_containers/inline_deque.h",
  "$dir_pw_containers/public/pw_containers/inline_queue.h",
  "$dir_pw_chrono/public/pw_chrono/system_clock.h",
  "$dir_pw_chrono/public/pw_chrono/system_timer.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_interrupt/public/pw_interrupt/context.h",
  "$dir_pw_i2c/public/pw_i2c/initiator.h",
  "$dir_pw_log_tokenized/public/pw_log_tokenized/handler.h",
  "$dir_pw_log_tokenized/public/pw_log_tokenized/metadata.h",
  "$dir_pw_rpc/public/pw_rpc/internal/config.h",
  "$dir_pw_rpc/public/pw_rpc/synchronous_call.h",
  "$dir_pw_string/public/pw_string/format.h",
  "$dir_pw_string/public/pw_string/string.h",
  "$dir_pw_function/public/pw_function/function.h",
  "$dir_pw_function/public/pw_function/pointer.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_status/public/pw_status/status.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_thread/public/pw_thread/test_thread_context.h",
  "$dir_pw_tokenizer/public/pw_tokenizer/encode_args.h",
  "$dir_pw_tokenizer/public/pw_tokenizer/tokenize.h",
  "$dir_pw_toolchain/public/pw_toolchain/no_destructor.h",
  "$dir_pw_varint/public/pw_varint/varint.h",
  "$dir_pw_varint/public/pw_varint/stream.h",
]

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",
    "index.rst",
    "module_guides.rst",
    "python_build.rst",
    "targets.rst",
    "third_party_support.rst",
  ]
  output_directory = target_gen_dir
  deps = [
    ":core_docs",
    ":generate_doxygen",
    ":module_docs",
    ":release_notes",
    ":static_assets",
    ":target_docs",
    ":templates",
    ":third_party_docs",
    "$dir_pigweed/seed:docs",
    "$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" ]
}