# 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_pigweed/Kconfig.zephyr", "$dir_pw_async2/examples/coro_blinky_loop.cc", "$dir_pw_async2/public/pw_async2/coro.h", "$dir_pw_build/pigweed.bazelrc", "$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/layout.html", "run_doxygen.py", ] sources = [ "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/docs/changelog.rst", "contributing/docs/guides.rst", "contributing/docs/index.rst", "contributing/docs/modules.rst", "contributing/index.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/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", "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", ] } # 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/perfetto: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/block/public/pw_allocator/block/alignable.h", "$dir_pw_allocator/block/public/pw_allocator/block/allocatable.h", "$dir_pw_allocator/block/public/pw_allocator/block/basic.h", "$dir_pw_allocator/block/public/pw_allocator/block/contiguous.h", "$dir_pw_allocator/block/public/pw_allocator/block/detailed_block.h", "$dir_pw_allocator/block/public/pw_allocator/block/iterable.h", "$dir_pw_allocator/block/public/pw_allocator/block/poisonable.h", "$dir_pw_allocator/block/public/pw_allocator/block/result.h", "$dir_pw_allocator/block/public/pw_allocator/block/with_layout.h", "$dir_pw_allocator/bucket/public/pw_allocator/bucket/fast_sorted.h", "$dir_pw_allocator/bucket/public/pw_allocator/bucket/sequenced.h", "$dir_pw_allocator/bucket/public/pw_allocator/bucket/sorted.h", "$dir_pw_allocator/bucket/public/pw_allocator/bucket/unordered.h", "$dir_pw_allocator/public/pw_allocator/allocator.h", "$dir_pw_allocator/public/pw_allocator/allocator_as_pool.h", "$dir_pw_allocator/public/pw_allocator/best_fit.h", "$dir_pw_allocator/public/pw_allocator/block_allocator.h", "$dir_pw_allocator/public/pw_allocator/bucket_allocator.h", "$dir_pw_allocator/public/pw_allocator/buddy_allocator.h", "$dir_pw_allocator/public/pw_allocator/buffer.h", "$dir_pw_allocator/public/pw_allocator/bump_allocator.h", "$dir_pw_allocator/public/pw_allocator/capability.h", "$dir_pw_allocator/public/pw_allocator/chunk_pool.h", "$dir_pw_allocator/public/pw_allocator/config.h", "$dir_pw_allocator/public/pw_allocator/deallocator.h", "$dir_pw_allocator/public/pw_allocator/fallback_allocator.h", "$dir_pw_allocator/public/pw_allocator/first_fit.h", "$dir_pw_allocator/public/pw_allocator/fragmentation.h", "$dir_pw_allocator/public/pw_allocator/fuzzing.h", "$dir_pw_allocator/public/pw_allocator/layout.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/pmr_allocator.h", "$dir_pw_allocator/public/pw_allocator/pool.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_allocator/public/pw_allocator/typed_pool.h", "$dir_pw_allocator/public/pw_allocator/unique_ptr.h", "$dir_pw_allocator/public/pw_allocator/worst_fit.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/allocate_task.h", "$dir_pw_async2/public/pw_async2/coro.h", "$dir_pw_async2/public/pw_async2/coro_or_else_task.h", "$dir_pw_async2/public/pw_async2/dispatcher.h", "$dir_pw_async2/public/pw_async2/dispatcher_base.h", "$dir_pw_async2/public/pw_async2/enqueue_heap_func.h", "$dir_pw_async2/public/pw_async2/join.h", "$dir_pw_async2/public/pw_async2/once_sender.h", "$dir_pw_async2/public/pw_async2/pend_func_task.h", "$dir_pw_async2/public/pw_async2/pendable_as_task.h", "$dir_pw_async2/public/pw_async2/poll.h", "$dir_pw_async2/public/pw_async2/simulated_time_provider.h", "$dir_pw_async2/public/pw_async2/system_time_provider.h", "$dir_pw_async2/public/pw_async2/time_provider.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/controller2.h", "$dir_pw_bluetooth/public/pw_bluetooth/gatt/client2.h", "$dir_pw_bluetooth/public/pw_bluetooth/gatt/server2.h", "$dir_pw_bluetooth/public/pw_bluetooth/low_energy/central2.h", "$dir_pw_bluetooth/public/pw_bluetooth/low_energy/channel.h", "$dir_pw_bluetooth/public/pw_bluetooth/low_energy/connection2.h", "$dir_pw_bluetooth/public/pw_bluetooth/low_energy/peripheral2.h", "$dir_pw_bluetooth_proxy/public/pw_bluetooth_proxy/h4_packet.h", "$dir_pw_bluetooth_proxy/public/pw_bluetooth_proxy/proxy_host.h", "$dir_pw_bluetooth_sapphire/public/pw_bluetooth_sapphire/peripheral.h", "$dir_pw_build/public/pw_build/linker_symbol.h", "$dir_pw_build/public/pw_build/must_place.ld.h", "$dir_pw_bytes/public/pw_bytes/alignment.h", "$dir_pw_bytes/public/pw_bytes/bit.h", "$dir_pw_bytes/public/pw_bytes/byte_builder.h", "$dir_pw_bytes/public/pw_bytes/packed_ptr.h", "$dir_pw_channel/public/pw_channel/channel.h", "$dir_pw_channel/public/pw_channel/epoll_channel.h", "$dir_pw_channel/public/pw_channel/forwarding_channel.h", "$dir_pw_channel/public/pw_channel/loopback_channel.h", "$dir_pw_channel/public/pw_channel/rp2_stdio_channel.h", "$dir_pw_channel/public/pw_channel/stream_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/simulated_system_clock.h", "$dir_pw_chrono/public/pw_chrono/system_clock.h", "$dir_pw_chrono/public/pw_chrono/system_timer.h", "$dir_pw_chrono/public/pw_chrono/virtual_clock.h", "$dir_pw_clock_tree/public/pw_clock_tree/clock_tree.h", "$dir_pw_clock_tree_mcuxpresso/public/pw_clock_tree_mcuxpresso/clock_tree.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_containers/public/pw_containers/internal/aa_tree.h", "$dir_pw_containers/public/pw_containers/internal/intrusive_list.h", "$dir_pw_containers/public/pw_containers/intrusive_forward_list.h", "$dir_pw_containers/public/pw_containers/intrusive_list.h", "$dir_pw_containers/public/pw_containers/intrusive_map.h", "$dir_pw_containers/public/pw_containers/intrusive_multimap.h", "$dir_pw_containers/public/pw_containers/intrusive_multiset.h", "$dir_pw_containers/public/pw_containers/intrusive_set.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_digital_io/public/pw_digital_io/digital_io_mock.h", "$dir_pw_display/public/pw_display/color.h", "$dir_pw_elf/public/pw_elf/reader.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_hdlc/public/pw_hdlc/router.h", "$dir_pw_hex_dump/public/pw_hex_dump/hex_dump.h", "$dir_pw_hex_dump/public/pw_hex_dump/log_bytes.h", "$dir_pw_i2c/public/pw_i2c/address.h", "$dir_pw_i2c/public/pw_i2c/device.h", "$dir_pw_i2c/public/pw_i2c/i2c_service.h", "$dir_pw_i2c/public/pw_i2c/initiator.h", "$dir_pw_i2c/public/pw_i2c/initiator_gmock.h", "$dir_pw_i2c/public/pw_i2c/initiator_mock.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/config.h", "$dir_pw_log_tokenized/public/pw_log_tokenized/handler.h", "$dir_pw_log_tokenized/public/pw_log_tokenized/metadata.h", "$dir_pw_malloc/public/pw_malloc/config.h", "$dir_pw_malloc/public/pw_malloc/malloc.h", "$dir_pw_multibuf/public/pw_multibuf/allocator.h", "$dir_pw_multibuf/public/pw_multibuf/chunk.h", "$dir_pw_multibuf/public/pw_multibuf/from_span.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/simple_allocator_for_test.h", "$dir_pw_multibuf/public/pw_multibuf/single_chunk_region_tracker.h", "$dir_pw_multibuf/public/pw_multibuf/stream.h", "$dir_pw_numeric/public/pw_numeric/integer_division.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/apply.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/channel.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_status/public/pw_status/status_with_size.h", "$dir_pw_status/public/pw_status/try.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/utf_codecs.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_system/public/pw_system/system.h", "$dir_pw_third_party/freertos/pw_assert_stack_overflow_hook.cc", "$dir_pw_third_party/freertos/static_task_allocation.cc", "$dir_pw_thread/public/pw_thread/options.h", "$dir_pw_thread/public/pw_thread/test_thread_context.h", "$dir_pw_thread/public/pw_thread/thread.h", "$dir_pw_tokenizer/public/pw_tokenizer/config.h", "$dir_pw_tokenizer/public/pw_tokenizer/detokenize.h", "$dir_pw_tokenizer/public/pw_tokenizer/encode_args.h", "$dir_pw_tokenizer/public/pw_tokenizer/enum.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_uart/public/pw_uart/blocking_adapter.h", "$dir_pw_uart/public/pw_uart/stream.h", "$dir_pw_uart/public/pw_uart/uart.h", "$dir_pw_uart/public/pw_uart/uart_base.h", "$dir_pw_uart/public/pw_uart/uart_non_blocking.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_unit_test/public/pw_unit_test/status_macros.h", "$dir_pw_unit_test/public/pw_unit_test/test_record_event_handler.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/html/index.html", "$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", "bazel_compatibility.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:docs", ] # Extra Python deps are required to set the PYTHONPATH so # automodule, autoclass or autofunction RST directives work in # sphinx. python_deps = [ "$dir_pw_env_setup:core_pigweed_python_packages" ] }