1# Copyright 2019 The Pigweed Authors 2# 3# Licensed under the Apache License, Version 2.0 (the "License"); you may not 4# use this file except in compliance with the License. You may obtain a copy of 5# the License at 6# 7# https://www.apache.org/licenses/LICENSE-2.0 8# 9# Unless required by applicable law or agreed to in writing, software 10# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 11# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12# License for the specific language governing permissions and limitations under 13# the License. 14 15import("//build_overrides/pigweed.gni") 16 17import("$dir_pw_build/python.gni") 18import("$dir_pw_build/python_action.gni") 19import("$dir_pw_docgen/docs.gni") 20 21pw_doc_group("static_assets") { 22 inputs = [ 23 "_static/css/pigweed.css", 24 "_static/js/changelog.js", 25 "_static/js/pigweed.js", 26 "_static/pw_logo.ico", 27 "_static/pw_logo.svg", 28 ] 29} 30 31# Note: These may be useful for downstream projects, which is why they are 32# split out from the overall docgen target below. 33pw_doc_group("core_docs") { 34 inputs = [ 35 "$dir_pw_build/py/gn_tests/BUILD.gn", 36 "$dir_pw_build/py/pw_build/generate_python_wheel_cache.py", 37 "$dir_pw_build/python.gni", 38 "$dir_pw_build/python_gn_args.gni", 39 "layout/page.html", 40 "run_doxygen.py", 41 ] 42 sources = [ 43 "blog/01-kudzu.rst", 44 "blog/02-bazel-feature-flags.rst", 45 "blog/index.rst", 46 "code_of_conduct.rst", 47 "code_reviews.rst", 48 "concepts/index.rst", 49 "contributing/docs/changelog.rst", 50 "contributing/docs/index.rst", 51 "contributing/docs/modules.rst", 52 "contributing/docs/website.rst", 53 "contributing/index.rst", 54 "editors.rst", 55 "embedded_cpp_guide.rst", 56 "facades.rst", 57 "faq.rst", 58 "get_started/bazel.rst", 59 "get_started/bazel_integration.rst", 60 "get_started/first_time_setup.rst", 61 "get_started/index.rst", 62 "get_started/upstream.rst", 63 "get_started/zephyr.rst", 64 "glossary.rst", 65 "infra/ci_cq_intro.rst", 66 "infra/github.rst", 67 "infra/index.rst", 68 "infra/rollers.rst", 69 "mission.rst", 70 "module_structure.rst", 71 "os/index.rst", 72 "os/zephyr/index.rst", 73 "os/zephyr/kconfig.rst", 74 "overview.rst", 75 "size_optimizations.rst", 76 "style/cli.rst", 77 "style/commit_message.rst", 78 "style/cpp.rst", 79 "style/doxygen.rst", 80 "style/protobuf.rst", 81 "style/rest.rst", 82 "style/writing.rst", 83 "style_guide.rst", 84 ] 85} 86 87# Documentation for upstream Pigweed targets. 88group("target_docs") { 89 deps = [ 90 "$dir_pigweed/targets/android:target_docs", 91 "$dir_pigweed/targets/apollo4:target_docs", 92 "$dir_pigweed/targets/apollo4_pw_system:target_docs", 93 "$dir_pigweed/targets/arduino:target_docs", 94 "$dir_pigweed/targets/docs:target_docs", 95 "$dir_pigweed/targets/emcraft_sf2_som:docs", 96 "$dir_pigweed/targets/host:target_docs", 97 "$dir_pigweed/targets/host_device_simulator:target_docs", 98 "$dir_pigweed/targets/lm3s6965evb_qemu:target_docs", 99 "$dir_pigweed/targets/mimxrt595_evk:target_docs", 100 "$dir_pigweed/targets/rp2040:target_docs", 101 "$dir_pigweed/targets/stm32f429i_disc1:target_docs", 102 "$dir_pigweed/targets/stm32f429i_disc1_stm32cube:target_docs", 103 ] 104} 105 106group("module_docs") { 107 deps = pw_module_docs 108} 109 110group("third_party_docs") { 111 deps = [ 112 "$dir_pigweed/third_party/abseil-cpp:docs", 113 "$dir_pigweed/third_party/boringssl:docs", 114 "$dir_pigweed/third_party/emboss:docs", 115 "$dir_pigweed/third_party/freertos:docs", 116 "$dir_pigweed/third_party/fuchsia:docs", 117 "$dir_pigweed/third_party/fuzztest:docs", 118 "$dir_pigweed/third_party/googletest:docs", 119 "$dir_pigweed/third_party/nanopb:docs", 120 "$dir_pigweed/third_party/perfetto:docs", 121 "$dir_pigweed/third_party/re2:docs", 122 "$dir_pigweed/third_party/tinyusb:docs", 123 ] 124} 125 126# All sources with doxygen comment blocks. 127_doxygen_input_files = [ # keep-sorted: start 128 "$dir_pw_alignment/public/pw_alignment/alignment.h", 129 "$dir_pw_allocator/public/pw_allocator/allocator.h", 130 "$dir_pw_allocator/public/pw_allocator/allocator_as_pool.h", 131 "$dir_pw_allocator/public/pw_allocator/as_pmr_allocator.h", 132 "$dir_pw_allocator/public/pw_allocator/best_fit_block_allocator.h", 133 "$dir_pw_allocator/public/pw_allocator/block.h", 134 "$dir_pw_allocator/public/pw_allocator/block_allocator_base.h", 135 "$dir_pw_allocator/public/pw_allocator/bucket.h", 136 "$dir_pw_allocator/public/pw_allocator/bucket_block_allocator.h", 137 "$dir_pw_allocator/public/pw_allocator/buddy_allocator.h", 138 "$dir_pw_allocator/public/pw_allocator/buffer.h", 139 "$dir_pw_allocator/public/pw_allocator/bump_allocator.h", 140 "$dir_pw_allocator/public/pw_allocator/capability.h", 141 "$dir_pw_allocator/public/pw_allocator/chunk_pool.h", 142 "$dir_pw_allocator/public/pw_allocator/deallocator.h", 143 "$dir_pw_allocator/public/pw_allocator/dual_first_fit_block_allocator.h", 144 "$dir_pw_allocator/public/pw_allocator/fallback_allocator.h", 145 "$dir_pw_allocator/public/pw_allocator/first_fit_block_allocator.h", 146 "$dir_pw_allocator/public/pw_allocator/fragmentation.h", 147 "$dir_pw_allocator/public/pw_allocator/fuzzing.h", 148 "$dir_pw_allocator/public/pw_allocator/last_fit_block_allocator.h", 149 "$dir_pw_allocator/public/pw_allocator/layout.h", 150 "$dir_pw_allocator/public/pw_allocator/libc_allocator.h", 151 "$dir_pw_allocator/public/pw_allocator/metrics.h", 152 "$dir_pw_allocator/public/pw_allocator/null_allocator.h", 153 "$dir_pw_allocator/public/pw_allocator/pool.h", 154 "$dir_pw_allocator/public/pw_allocator/size_reporter.h", 155 "$dir_pw_allocator/public/pw_allocator/synchronized_allocator.h", 156 "$dir_pw_allocator/public/pw_allocator/test_harness.h", 157 "$dir_pw_allocator/public/pw_allocator/testing.h", 158 "$dir_pw_allocator/public/pw_allocator/tracking_allocator.h", 159 "$dir_pw_allocator/public/pw_allocator/typed_pool.h", 160 "$dir_pw_allocator/public/pw_allocator/unique_ptr.h", 161 "$dir_pw_allocator/public/pw_allocator/worst_fit_block_allocator.h", 162 "$dir_pw_analog/public/pw_analog/analog_input.h", 163 "$dir_pw_analog/public/pw_analog/microvolt_input.h", 164 "$dir_pw_async/public/pw_async/context.h", 165 "$dir_pw_async/public/pw_async/dispatcher.h", 166 "$dir_pw_async/public/pw_async/fake_dispatcher_fixture.h", 167 "$dir_pw_async/public/pw_async/function_dispatcher.h", 168 "$dir_pw_async/public/pw_async/heap_dispatcher.h", 169 "$dir_pw_async/public/pw_async/task.h", 170 "$dir_pw_async/public/pw_async/task_function.h", 171 "$dir_pw_async2/public/pw_async2/allocate_task.h", 172 "$dir_pw_async2/public/pw_async2/coro.h", 173 "$dir_pw_async2/public/pw_async2/dispatcher.h", 174 "$dir_pw_async2/public/pw_async2/dispatcher_base.h", 175 "$dir_pw_async2/public/pw_async2/pend_func_task.h", 176 "$dir_pw_async2/public/pw_async2/pendable_as_task.h", 177 "$dir_pw_async2/public/pw_async2/poll.h", 178 "$dir_pw_async2_basic/public_overrides/pw_async2/dispatcher_native.h", 179 "$dir_pw_async_basic/public/pw_async_basic/dispatcher.h", 180 "$dir_pw_base64/public/pw_base64/base64.h", 181 "$dir_pw_bluetooth/public/pw_bluetooth/gatt/client.h", 182 "$dir_pw_bluetooth/public/pw_bluetooth/gatt/server.h", 183 "$dir_pw_bluetooth/public/pw_bluetooth/host.h", 184 "$dir_pw_bluetooth/public/pw_bluetooth/low_energy/central.h", 185 "$dir_pw_bluetooth/public/pw_bluetooth/low_energy/connection.h", 186 "$dir_pw_bluetooth/public/pw_bluetooth/low_energy/peripheral.h", 187 "$dir_pw_bluetooth_proxy/public/pw_bluetooth_proxy/common.h", 188 "$dir_pw_bluetooth_proxy/public/pw_bluetooth_proxy/proxy_host.h", 189 "$dir_pw_build/public/pw_build/must_place.ld.h", 190 "$dir_pw_bytes/public/pw_bytes/alignment.h", 191 "$dir_pw_bytes/public/pw_bytes/bit.h", 192 "$dir_pw_bytes/public/pw_bytes/byte_builder.h", 193 "$dir_pw_channel/public/pw_channel/channel.h", 194 "$dir_pw_channel/public/pw_channel/epoll_channel.h", 195 "$dir_pw_channel/public/pw_channel/forwarding_channel.h", 196 "$dir_pw_channel/public/pw_channel/loopback_channel.h", 197 "$dir_pw_chre/public/pw_chre/chre.h", 198 "$dir_pw_chre/public/pw_chre/host_link.h", 199 "$dir_pw_chrono/public/pw_chrono/system_clock.h", 200 "$dir_pw_chrono/public/pw_chrono/system_timer.h", 201 "$dir_pw_clock_tree/public/pw_clock_tree/clock_tree.h", 202 "$dir_pw_clock_tree_mcuxpresso/public/pw_clock_tree_mcuxpresso/clock_tree.h", 203 "$dir_pw_containers/public/pw_containers/filtered_view.h", 204 "$dir_pw_containers/public/pw_containers/inline_deque.h", 205 "$dir_pw_containers/public/pw_containers/inline_queue.h", 206 "$dir_pw_containers/public/pw_containers/inline_var_len_entry_queue.h", 207 "$dir_pw_crypto/public/pw_crypto/ecdsa.h", 208 "$dir_pw_crypto/public/pw_crypto/sha256.h", 209 "$dir_pw_digital_io/public/pw_digital_io/digital_io.h", 210 "$dir_pw_function/public/pw_function/function.h", 211 "$dir_pw_function/public/pw_function/pointer.h", 212 "$dir_pw_function/public/pw_function/scope_guard.h", 213 "$dir_pw_hdlc/public/pw_hdlc/decoder.h", 214 "$dir_pw_hdlc/public/pw_hdlc/encoder.h", 215 "$dir_pw_hdlc/public/pw_hdlc/router.h", 216 "$dir_pw_i2c/public/pw_i2c/address.h", 217 "$dir_pw_i2c/public/pw_i2c/device.h", 218 "$dir_pw_i2c/public/pw_i2c/i2c_service.h", 219 "$dir_pw_i2c/public/pw_i2c/initiator.h", 220 "$dir_pw_i2c/public/pw_i2c/initiator_gmock.h", 221 "$dir_pw_i2c/public/pw_i2c/initiator_mock.h", 222 "$dir_pw_i2c/public/pw_i2c/register_device.h", 223 "$dir_pw_i2c_linux/public/pw_i2c_linux/initiator.h", 224 "$dir_pw_interrupt/public/pw_interrupt/context.h", 225 "$dir_pw_json/public/pw_json/builder.h", 226 "$dir_pw_kvs/public/pw_kvs/key_value_store.h", 227 "$dir_pw_kvs/pw_kvs_private/config.h", 228 "$dir_pw_log/public/pw_log/tokenized_args.h", 229 "$dir_pw_log_string/public/pw_log_string/handler.h", 230 "$dir_pw_log_tokenized/public/pw_log_tokenized/base64.h", 231 "$dir_pw_log_tokenized/public/pw_log_tokenized/handler.h", 232 "$dir_pw_log_tokenized/public/pw_log_tokenized/metadata.h", 233 "$dir_pw_malloc/public/pw_malloc/config.h", 234 "$dir_pw_malloc/public/pw_malloc/malloc.h", 235 "$dir_pw_multibuf/public/pw_multibuf/allocator.h", 236 "$dir_pw_multibuf/public/pw_multibuf/chunk.h", 237 "$dir_pw_multibuf/public/pw_multibuf/header_chunk_region_tracker.h", 238 "$dir_pw_multibuf/public/pw_multibuf/multibuf.h", 239 "$dir_pw_multibuf/public/pw_multibuf/simple_allocator.h", 240 "$dir_pw_multibuf/public/pw_multibuf/simple_allocator_for_test.h", 241 "$dir_pw_multibuf/public/pw_multibuf/single_chunk_region_tracker.h", 242 "$dir_pw_multibuf/public/pw_multibuf/stream.h", 243 "$dir_pw_perf_test/public/pw_perf_test/event_handler.h", 244 "$dir_pw_perf_test/public/pw_perf_test/perf_test.h", 245 "$dir_pw_polyfill/public/pw_polyfill/language_feature_macros.h", 246 "$dir_pw_polyfill/public/pw_polyfill/standard.h", 247 "$dir_pw_preprocessor/public/pw_preprocessor/compiler.h", 248 "$dir_pw_protobuf/public/pw_protobuf/find.h", 249 "$dir_pw_random/public/pw_random/random.h", 250 "$dir_pw_random/public/pw_random/xor_shift.h", 251 "$dir_pw_rpc/public/pw_rpc/channel.h", 252 "$dir_pw_rpc/public/pw_rpc/internal/config.h", 253 "$dir_pw_rpc/public/pw_rpc/synchronous_call.h", 254 "$dir_pw_span/public/pw_span/internal/config.h", 255 "$dir_pw_spi/public/pw_spi/chip_selector.h", 256 "$dir_pw_spi/public/pw_spi/chip_selector_digital_out.h", 257 "$dir_pw_status/public/pw_status/status.h", 258 "$dir_pw_status/public/pw_status/try.h", 259 "$dir_pw_stream/public/pw_stream/stream.h", 260 "$dir_pw_stream_uart_linux/public/pw_stream_uart_linux/stream.h", 261 "$dir_pw_string/public/pw_string/format.h", 262 "$dir_pw_string/public/pw_string/string.h", 263 "$dir_pw_string/public/pw_string/string_builder.h", 264 "$dir_pw_string/public/pw_string/util.h", 265 "$dir_pw_sync/public/pw_sync/binary_semaphore.h", 266 "$dir_pw_sync/public/pw_sync/borrow.h", 267 "$dir_pw_sync/public/pw_sync/counting_semaphore.h", 268 "$dir_pw_sync/public/pw_sync/inline_borrowable.h", 269 "$dir_pw_sync/public/pw_sync/interrupt_spin_lock.h", 270 "$dir_pw_sync/public/pw_sync/lock_annotations.h", 271 "$dir_pw_sync/public/pw_sync/mutex.h", 272 "$dir_pw_sync/public/pw_sync/thread_notification.h", 273 "$dir_pw_sync/public/pw_sync/timed_mutex.h", 274 "$dir_pw_sync/public/pw_sync/timed_thread_notification.h", 275 "$dir_pw_sync/public/pw_sync/virtual_basic_lockable.h", 276 "$dir_pw_sys_io/public/pw_sys_io/sys_io.h", 277 "$dir_pw_third_party/freertos/pw_assert_stack_overflow_hook.cc", 278 "$dir_pw_third_party/freertos/static_task_allocation.cc", 279 "$dir_pw_thread/public/pw_thread/test_thread_context.h", 280 "$dir_pw_thread/public/pw_thread/thread.h", 281 "$dir_pw_tokenizer/public/pw_tokenizer/config.h", 282 "$dir_pw_tokenizer/public/pw_tokenizer/detokenize.h", 283 "$dir_pw_tokenizer/public/pw_tokenizer/encode_args.h", 284 "$dir_pw_tokenizer/public/pw_tokenizer/nested_tokenization.h", 285 "$dir_pw_tokenizer/public/pw_tokenizer/token_database.h", 286 "$dir_pw_tokenizer/public/pw_tokenizer/tokenize.h", 287 "$dir_pw_toolchain/public/pw_toolchain/no_destructor.h", 288 "$dir_pw_transfer/public/pw_transfer/atomic_file_transfer_handler.h", 289 "$dir_pw_uart/public/pw_uart/uart.h", 290 "$dir_pw_unit_test/light_public_overrides/pw_unit_test/framework_backend.h", 291 "$dir_pw_unit_test/public/pw_unit_test/config.h", 292 "$dir_pw_unit_test/public/pw_unit_test/event_handler.h", 293 "$dir_pw_unit_test/public/pw_unit_test/googletest_handler_adapter.h", 294 "$dir_pw_unit_test/public/pw_unit_test/googletest_style_event_handler.h", 295 "$dir_pw_unit_test/public/pw_unit_test/logging_event_handler.h", 296 "$dir_pw_unit_test/public/pw_unit_test/multi_event_handler.h", 297 "$dir_pw_unit_test/public/pw_unit_test/printf_event_handler.h", 298 "$dir_pw_unit_test/public/pw_unit_test/simple_printing_event_handler.h", 299 "$dir_pw_unit_test/public/pw_unit_test/static_library_support.h", 300 "$dir_pw_unit_test/public/pw_unit_test/test_record_event_handler.h", 301 "$dir_pw_varint/public/pw_varint/stream.h", 302 "$dir_pw_varint/public/pw_varint/varint.h", 303 "$dir_pw_work_queue/public/pw_work_queue/work_queue.h", 304] # keep-sorted: end 305 306pw_python_action("generate_doxygen") { 307 _output_dir = "docs/doxygen" 308 script = "run_doxygen.py" 309 inputs = [ 310 "//PIGWEED_MODULES", 311 "Doxyfile", 312 ] 313 inputs += _doxygen_input_files 314 args = [ 315 "--gn-root", 316 rebase_path("//", root_build_dir), 317 "--pigweed-modules-file", 318 rebase_path("//PIGWEED_MODULES", root_build_dir), 319 "--output-dir", 320 _output_dir, 321 "--doxygen-config", 322 rebase_path("Doxyfile", root_build_dir), 323 "--include-paths", 324 ] 325 args += rebase_path(_doxygen_input_files, root_build_dir) 326 outputs = [ 327 "$root_build_dir/$_output_dir/html/index.html", 328 "$root_build_dir/$_output_dir/xml/index.xml", 329 ] 330} 331 332pw_doc_gen("docs") { 333 conf = "conf.py" 334 sources = [ 335 # Note: These must use the "docs" prefix for links and image references. In 336 # contrast, the pw_doc_group above should not use the docs prefix. 337 "automated_analysis.rst", 338 "build_system.rst", 339 "changelog.rst", 340 "index.rst", 341 "modules.rst", 342 "python_build.rst", 343 "targets.rst", 344 "third_party_support.rst", 345 ] 346 output_directory = target_gen_dir 347 deps = [ 348 ":core_docs", 349 ":generate_doxygen", 350 ":module_docs", 351 ":static_assets", 352 ":target_docs", 353 ":third_party_docs", 354 "$dir_pigweed/kudzu:docs", 355 "$dir_pigweed/seed:seeds", 356 "$dir_pw_env_setup:python.install", 357 ] 358 359 # Required to set the PYTHONPATH so automodule, autoclass or autofunction RST 360 # directives work. 361 python_metadata_deps = [ "$dir_pw_env_setup:core_pigweed_python_packages" ] 362} 363
