From 3f523d3ff8974c6c0b97e745a6902c4f77925876 Mon Sep 17 00:00:00 2001 From: Hugo McNally Date: Sun, 12 Feb 2023 14:47:22 +0000 Subject: [PATCH] [doc] Rewrite most frontmatters to Markdown titles Completely throw away the frontmatter and only keep the title which is turned into a Markdown title. To recreate the rewrite, run the added script, `util/rewrite_frontmatter.py`, in the root of the repo. ```sh python3 util/rewrite_frontmatter.py ./ ``` Signed-off-by: Hugo McNally Co-authored-by: Amaury Pouly --- doc/contributing/README.md | 4 +- doc/contributing/bazel_notes.md | 4 +- doc/contributing/ci/README.md | 4 +- .../detailed_contribution_guide/README.md | 4 +- doc/contributing/directory_structure.md | 4 +- doc/contributing/dv/methodology/README.md | 4 +- .../dv/sec_cm_dv_framework/README.md | 4 +- doc/contributing/fpga/get_a_board.md | 4 +- doc/contributing/fpga/ref_manual_fpga.md | 4 +- doc/contributing/github_notes.md | 4 +- doc/contributing/hw/comportability/README.md | 4 +- doc/contributing/hw/design.md | 4 +- doc/contributing/hw/methodology.md | 4 +- doc/contributing/hw/vendor.md | 4 +- doc/contributing/style_guides/README.md | 4 +- .../style_guides/asm_coding_style.md | 4 +- .../style_guides/c_cpp_coding_style.md | 4 +- .../style_guides/guidance_for_volatile.md | 4 +- .../style_guides/hjson_usage_style.md | 4 +- .../style_guides/markdown_usage_style.md | 4 +- .../style_guides/otbn_style_guide.md | 4 +- .../style_guides/python_coding_style.md | 4 +- .../sw/device_interface_functions.md | 4 +- doc/contributing/sw/otbn_sw.md | 4 +- doc/contributing/system_list.md | 4 +- doc/guides/getting_started/src/README.md | 7 +-- doc/guides/getting_started/src/build_docs.md | 4 +- doc/guides/getting_started/src/build_sw.md | 6 +- .../getting_started/src/install_openocd.md | 4 +- .../src/install_vivado/README.md | 4 +- doc/guides/getting_started/src/setup_dv.md | 6 +- .../getting_started/src/setup_formal.md | 6 +- doc/guides/getting_started/src/setup_fpga.md | 6 +- .../getting_started/src/setup_verilator.md | 6 +- doc/introduction.md | 4 +- doc/project_governance/README.md | 4 +- doc/project_governance/checklist/README.md | 4 +- doc/project_governance/committers.md | 4 +- doc/project_governance/development_stages.md | 5 +- doc/project_governance/rfc_process.md | 4 +- doc/project_governance/technical_committee.md | 4 +- doc/rust_for_c_devs.md | 4 +- doc/security/README.md | 5 +- .../implementation_guidelines/README.md | 4 +- .../hardware/README.md | 4 +- doc/security/logical_security_model/README.md | 4 +- doc/security/specs/README.md | 4 +- doc/security/specs/attestation/README.md | 4 +- .../specs/device_life_cycle/README.md | 4 +- .../specs/device_provisioning/README.md | 4 +- doc/security/specs/firmware_update/README.md | 4 +- .../specs/identities_and_root_keys/README.md | 4 +- .../specs/ownership_transfer/README.md | 4 +- doc/security/specs/secure_boot/README.md | 4 +- doc/security/threat_model/README.md | 4 +- doc/use_cases/README.md | 4 +- .../platform_integrity_module/README.md | 4 +- doc/use_cases/tpm/README.md | 4 +- doc/use_cases/u2f/README.md | 4 +- hw/README.md | 5 +- hw/dv/README.md | 4 +- hw/dv/doc/dv_doc_template.md | 5 +- hw/dv/sv/README.md | 4 +- hw/dv/sv/alert_esc_agent/README.md | 4 +- hw/dv/sv/bus_params_pkg/README.md | 4 +- hw/dv/sv/cip_lib/README.md | 4 +- hw/dv/sv/common_ifs/README.md | 4 +- hw/dv/sv/csr_utils/README.md | 4 +- hw/dv/sv/csrng_agent/README.md | 4 +- hw/dv/sv/dv_lib/README.md | 4 +- hw/dv/sv/flash_phy_prim_agent/README.md | 4 +- hw/dv/sv/i2c_agent/README.md | 4 +- hw/dv/sv/jtag_agent/README.md | 4 +- hw/dv/sv/jtag_dmi_agent/README.md | 4 +- hw/dv/sv/jtag_riscv_agent/README.md | 4 +- hw/dv/sv/key_sideload_agent/README.md | 4 +- hw/dv/sv/kmac_app_agent/README.md | 4 +- hw/dv/sv/mem_bkdr_scb/README.md | 4 +- hw/dv/sv/mem_bkdr_util/README.md | 4 +- hw/dv/sv/mem_model/README.md | 4 +- hw/dv/sv/pattgen_agent/README.md | 4 +- hw/dv/sv/push_pull_agent/README.md | 4 +- hw/dv/sv/pwm_monitor/README.md | 4 +- hw/dv/sv/rng_agent/README.md | 4 +- hw/dv/sv/scoreboard/README.md | 4 +- hw/dv/sv/sim_sram/README.md | 4 +- hw/dv/sv/spi_agent/README.md | 4 +- hw/dv/sv/str_utils/README.md | 4 +- hw/dv/sv/test_vectors/README.md | 4 +- hw/dv/sv/tl_agent/README.md | 4 +- hw/dv/sv/uart_agent/README.md | 4 +- hw/dv/sv/usb20_agent/README.md | 4 +- hw/dv/tools/README.md | 4 +- hw/dv/tools/ralgen/README.md | 4 +- hw/formal/README.md | 5 +- hw/ip/README.md | 4 +- hw/ip/adc_ctrl/README.md | 4 +- hw/ip/adc_ctrl/doc/checklist.md | 4 +- hw/ip/adc_ctrl/dv/README.md | 4 +- hw/ip/aes/README.md | 4 +- hw/ip/aes/doc/checklist.md | 4 +- hw/ip/aes/dv/README.md | 4 +- hw/ip/aon_timer/README.md | 4 +- hw/ip/aon_timer/doc/checklist.md | 4 +- hw/ip/aon_timer/dv/README.md | 4 +- hw/ip/clkmgr/README.md | 4 +- hw/ip/clkmgr/doc/checklist.md | 4 +- hw/ip/clkmgr/dv/README.md | 4 +- hw/ip/csrng/README.md | 4 +- hw/ip/csrng/doc/checklist.md | 4 +- hw/ip/csrng/dv/README.md | 4 +- hw/ip/edn/README.md | 4 +- hw/ip/edn/doc/checklist.md | 4 +- hw/ip/edn/dv/README.md | 4 +- hw/ip/entropy_src/README.md | 4 +- hw/ip/entropy_src/doc/checklist.md | 4 +- hw/ip/entropy_src/dv/README.md | 4 +- hw/ip/flash_ctrl/README.md | 4 +- hw/ip/flash_ctrl/doc/checklist.md | 4 +- hw/ip/flash_ctrl/dv/README.md | 4 +- hw/ip/gpio/README.md | 4 +- hw/ip/gpio/doc/checklist.md | 4 +- hw/ip/gpio/dv/README.md | 4 +- hw/ip/hmac/README.md | 4 +- hw/ip/hmac/doc/checklist.md | 4 +- hw/ip/hmac/dv/README.md | 4 +- hw/ip/i2c/README.md | 4 +- hw/ip/i2c/doc/checklist.md | 4 +- hw/ip/i2c/dv/README.md | 4 +- hw/ip/keymgr/README.md | 4 +- hw/ip/keymgr/doc/checklist.md | 4 +- hw/ip/keymgr/dv/README.md | 4 +- hw/ip/kmac/README.md | 4 +- hw/ip/kmac/doc/checklist.md | 4 +- hw/ip/kmac/dv/README.md | 4 +- hw/ip/lc_ctrl/README.md | 4 +- hw/ip/lc_ctrl/doc/checklist.md | 4 +- hw/ip/lc_ctrl/dv/README.md | 4 +- hw/ip/otbn/README.md | 4 +- hw/ip/otbn/doc/checklist.md | 4 +- hw/ip/otbn/doc/isa.md | 4 +- hw/ip/otbn/dv/README.md | 4 +- hw/ip/otbn/dv/doc/fcov.md | 4 +- hw/ip/otp_ctrl/README.md | 4 +- hw/ip/otp_ctrl/doc/checklist.md | 4 +- hw/ip/otp_ctrl/dv/README.md | 4 +- hw/ip/pattgen/README.md | 4 +- hw/ip/pattgen/doc/checklist.md | 4 +- hw/ip/pattgen/dv/README.md | 4 +- hw/ip/pinmux/README.md | 4 +- hw/ip/pinmux/doc/checklist.md | 4 +- hw/ip/pinmux/doc/dv/README.md | 4 +- hw/ip/prim/README.md | 4 +- hw/ip/prim/doc/prim_clock_gp_mux2.md | 4 +- hw/ip/prim/doc/prim_flash.md | 4 +- hw/ip/prim/doc/prim_keccak.md | 4 +- hw/ip/prim/doc/prim_lfsr.md | 4 +- hw/ip/prim/doc/prim_packer.md | 4 +- hw/ip/prim/doc/prim_packer_fifo.md | 4 +- hw/ip/prim/doc/prim_present.md | 4 +- hw/ip/prim/doc/prim_prince.md | 6 +- hw/ip/prim/doc/prim_ram_1p_scr.md | 4 +- hw/ip/prim/doc/prim_xoshiro256pp.md | 4 +- hw/ip/pwm/README.md | 4 +- hw/ip/pwm/doc/checklist.md | 4 +- hw/ip/pwm/dv/README.md | 4 +- hw/ip/pwrmgr/README.md | 4 +- hw/ip/pwrmgr/doc/checklist.md | 4 +- hw/ip/pwrmgr/dv/README.md | 4 +- hw/ip/rom_ctrl/README.md | 4 +- hw/ip/rom_ctrl/doc/checklist.md | 4 +- hw/ip/rom_ctrl/dv/README.md | 4 +- hw/ip/rstmgr/README.md | 4 +- hw/ip/rstmgr/doc/checklist.md | 4 +- hw/ip/rstmgr/dv/README.md | 4 +- hw/ip/rv_core_ibex/README.md | 4 +- hw/ip/rv_core_ibex/doc/checklist.md | 4 +- hw/ip/rv_core_ibex/dv/README.md | 4 +- hw/ip/rv_dm/README.md | 4 +- hw/ip/rv_dm/doc/checklist.md | 4 +- hw/ip/rv_dm/dv/README.md | 4 +- hw/ip/rv_timer/README.md | 4 +- hw/ip/rv_timer/doc/checklist.md | 4 +- hw/ip/rv_timer/dv/README.md | 4 +- hw/ip/spi_device/README.md | 4 +- hw/ip/spi_device/doc/checklist.md | 4 +- hw/ip/spi_device/dv/README.md | 4 +- hw/ip/spi_host/README.md | 4 +- hw/ip/spi_host/doc/checklist.md | 4 +- hw/ip/spi_host/dv/README.md | 4 +- hw/ip/sram_ctrl/README.md | 4 +- hw/ip/sram_ctrl/doc/checklist.md | 4 +- hw/ip/sram_ctrl/dv/README.md | 4 +- hw/ip/sysrst_ctrl/README.md | 4 +- hw/ip/sysrst_ctrl/doc/checklist.md | 4 +- hw/ip/sysrst_ctrl/dv/README.md | 4 +- hw/ip/tlul/README.md | 4 +- hw/ip/tlul/doc/TlulProtocolChecker.md | 4 +- hw/ip/tlul/doc/dv/README.md | 4 +- hw/ip/uart/README.md | 4 +- hw/ip/uart/doc/checklist.md | 4 +- hw/ip/uart/dv/README.md | 4 +- hw/ip/usbdev/README.md | 4 +- hw/ip/usbdev/doc/checklist.md | 4 +- hw/ip/usbdev/doc/wake_resume.md | 4 +- hw/ip/usbdev/dv/README.md | 4 +- hw/ip_templates/alert_handler/README.md | 4 +- .../alert_handler/doc/checklist.md | 4 +- hw/ip_templates/alert_handler/dv/README.md | 4 +- hw/ip_templates/rv_plic/README.md | 4 +- hw/ip_templates/rv_plic/doc/checklist.md | 4 +- hw/ip_templates/rv_plic/doc/dv/README.md | 4 +- hw/lint/README.md | 5 +- hw/top_earlgrey/README.md | 4 +- hw/top_earlgrey/doc/design/README.md | 4 +- hw/top_earlgrey/doc/specification.md | 4 +- hw/top_earlgrey/dv/README.md | 4 +- hw/top_earlgrey/ip/ast/README.md | 4 +- .../ip/pinmux/doc/autogen/pinout_asic.md | 4 +- .../ip/pinmux/doc/autogen/pinout_cw310.md | 4 +- hw/top_earlgrey/ip/sensor_ctrl/README.md | 4 +- .../ip/sensor_ctrl/doc/checklist.md | 4 +- hw/top_earlgrey/ip/xbar/doc/checklist.md | 4 +- .../ip_autogen/alert_handler/README.md | 4 +- .../ip_autogen/alert_handler/doc/checklist.md | 4 +- .../ip_autogen/alert_handler/dv/README.md | 4 +- hw/top_earlgrey/ip_autogen/rv_plic/README.md | 4 +- .../ip_autogen/rv_plic/doc/checklist.md | 4 +- .../ip_autogen/rv_plic/doc/dv/README.md | 4 +- site/docs/doxygen/main_page.md | 2 +- sw/README.md | 4 +- sw/device/README.md | 4 +- sw/device/lib/README.md | 4 +- sw/device/lib/dif/README.md | 4 +- sw/device/lib/dif/dif_adc_ctrl.md | 4 +- sw/device/lib/dif/dif_aes.md | 4 +- sw/device/lib/dif/dif_alert_handler.md | 4 +- sw/device/lib/dif/dif_aon_timer.md | 4 +- sw/device/lib/dif/dif_clkmgr.md | 4 +- sw/device/lib/dif/dif_csrng.md | 4 +- sw/device/lib/dif/dif_edn.md | 4 +- sw/device/lib/dif/dif_entropy_src.md | 4 +- sw/device/lib/dif/dif_flash_ctrl.md | 4 +- sw/device/lib/dif/dif_gpio.md | 4 +- sw/device/lib/dif/dif_hmac.md | 4 +- sw/device/lib/dif/dif_i2c.md | 4 +- sw/device/lib/dif/dif_keymgr.md | 4 +- sw/device/lib/dif/dif_kmac.md | 4 +- sw/device/lib/dif/dif_lc_ctrl.md | 4 +- sw/device/lib/dif/dif_otbn.md | 4 +- sw/device/lib/dif/dif_otp_ctrl.md | 4 +- sw/device/lib/dif/dif_pattgen.md | 4 +- sw/device/lib/dif/dif_pinmux.md | 4 +- sw/device/lib/dif/dif_pwm.md | 4 +- sw/device/lib/dif/dif_pwrmgr.md | 4 +- sw/device/lib/dif/dif_rom_ctrl.md | 4 +- sw/device/lib/dif/dif_rstmgr.md | 4 +- sw/device/lib/dif/dif_rv_core_ibex.md | 4 +- sw/device/lib/dif/dif_rv_plic.md | 4 +- sw/device/lib/dif/dif_rv_timer.md | 4 +- sw/device/lib/dif/dif_sensor_ctrl.md | 4 +- sw/device/lib/dif/dif_spi_device.md | 4 +- sw/device/lib/dif/dif_spi_host.md | 4 +- sw/device/lib/dif/dif_sram_ctrl.md | 4 +- sw/device/lib/dif/dif_sysrst_ctrl.md | 4 +- sw/device/lib/dif/dif_uart.md | 4 +- sw/device/lib/dif/dif_usbdev.md | 4 +- sw/device/lib/testing/README.md | 4 +- .../lib/testing/test_framework/README.md | 4 +- sw/device/silicon_creator/README.md | 4 +- sw/device/silicon_creator/manuf/README.md | 4 +- sw/device/silicon_creator/rom/README.md | 4 +- .../rom/doc/memory_protection.md | 4 +- sw/device/silicon_creator/rom/keys/README.md | 4 +- .../silicon_creator/rom_ext/doc/manifest.md | 6 +- sw/device/tests/README.md | 4 +- sw/doc/build_software.md | 4 +- sw/host/README.md | 4 +- sw/otbn/code-snippets/README.md | 4 +- third_party/coremark/README.md | 4 +- util/README.md | 4 +- util/doc/vendor.md | 4 +- util/dvsim/README.md | 4 +- util/dvsim/examples/testplanner/foo_dv_doc.md | 5 +- util/fpvgen/README.md | 4 +- util/i2csvg/smbus/SMBus.md | 4 +- util/ipgen/README.md | 4 +- util/reggen/README.md | 4 +- util/reggen/doc/setup_and_use.md | 4 +- util/rewrite_frontmatter.py | 61 +++++++++++++++++++ util/tlgen/README.md | 4 +- util/topgen/README.md | 4 +- util/uvmdvgen/README.md | 4 +- 293 files changed, 353 insertions(+), 898 deletions(-) create mode 100644 util/rewrite_frontmatter.py diff --git a/doc/contributing/README.md b/doc/contributing/README.md index fae9f5d8d409e..ac8f0893b6950 100644 --- a/doc/contributing/README.md +++ b/doc/contributing/README.md @@ -1,6 +1,4 @@ ---- -title: Contributing to OpenTitan ---- +# Contributing to OpenTitan Thank you for your interest in contributing to OpenTitan. This document provides some guidelines to making those contributions. diff --git a/doc/contributing/bazel_notes.md b/doc/contributing/bazel_notes.md index d589fe8e4ba67..92cc105a389e6 100644 --- a/doc/contributing/bazel_notes.md +++ b/doc/contributing/bazel_notes.md @@ -1,6 +1,4 @@ ---- -title: Bazel Notes ---- +# Bazel Notes Both OpenTitan hardware and software is built with Bazel. While our [Getting Started](https://docs.opentitan.org/doc/guides/getting_started/) guides detail some of the Bazel commands that can be used to build both types of artifacts, below are detailed notes on: diff --git a/doc/contributing/ci/README.md b/doc/contributing/ci/README.md index 3e55385d5fe7b..7e56b3ed3e514 100644 --- a/doc/contributing/ci/README.md +++ b/doc/contributing/ci/README.md @@ -1,6 +1,4 @@ ---- -title: "OpenTitan Continuous Integration" ---- +# OpenTitan Continuous Integration All changes to the OpenTitan source code are tested thoroughly in a continuous integration system. Tests run automatically when changes are proposed for inclusion by submitting a pull request, and on the `master` branch after changes are merged. diff --git a/doc/contributing/detailed_contribution_guide/README.md b/doc/contributing/detailed_contribution_guide/README.md index af81d3f5657d1..bcf9c81525190 100644 --- a/doc/contributing/detailed_contribution_guide/README.md +++ b/doc/contributing/detailed_contribution_guide/README.md @@ -1,6 +1,4 @@ ---- -title: "In-depth guide to contributing to OpenTitan" ---- +# In-depth guide to contributing to OpenTitan The way we work on OpenTitan is very similar to what is done in other collaborative open-source projects. For a brief overview see [Contributing to OpenTitan](../README.md). diff --git a/doc/contributing/directory_structure.md b/doc/contributing/directory_structure.md index b893f3b62342c..227785e433c5b 100644 --- a/doc/contributing/directory_structure.md +++ b/doc/contributing/directory_structure.md @@ -1,6 +1,4 @@ ---- -title: "Directory Structure" ---- +# Directory Structure This document provides an overview of the opentitan repository directory structure. The hierarchy underneath the root is fairly self explanatory, containing the following: diff --git a/doc/contributing/dv/methodology/README.md b/doc/contributing/dv/methodology/README.md index 1272ce2d95a68..ea0853a5c9ffb 100644 --- a/doc/contributing/dv/methodology/README.md +++ b/doc/contributing/dv/methodology/README.md @@ -1,6 +1,4 @@ ---- -title: "Design Verification Methodology within OpenTitan" ---- +# Design Verification Methodology within OpenTitan Verification within OpenTitan combines the challenges of industry-strength verification methodologies with open source ambitions. When in conflict, quality must win, and thus we aim to create a verification product that is equal to the quality required from a full production silicon chip tapeout. diff --git a/doc/contributing/dv/sec_cm_dv_framework/README.md b/doc/contributing/dv/sec_cm_dv_framework/README.md index 00adad2cdab9b..36085178f0974 100644 --- a/doc/contributing/dv/sec_cm_dv_framework/README.md +++ b/doc/contributing/dv/sec_cm_dv_framework/README.md @@ -1,6 +1,4 @@ ---- -title: "Security Countermeasure Verification Framework" ---- +# Security Countermeasure Verification Framework ## Purpose In a security chip, there are many hardening security countermeasures implemented in security blocks. diff --git a/doc/contributing/fpga/get_a_board.md b/doc/contributing/fpga/get_a_board.md index d7e05a6eed4ba..91aab9c889e93 100644 --- a/doc/contributing/fpga/get_a_board.md +++ b/doc/contributing/fpga/get_a_board.md @@ -1,6 +1,4 @@ ---- -title: "Get an FPGA Board" ---- +# Get an FPGA Board FPGA boards come at different price points, with the price being a good indicator for how much logic the FPGA can hold. The following sections give details of how to obtain our supported FPGA boards. diff --git a/doc/contributing/fpga/ref_manual_fpga.md b/doc/contributing/fpga/ref_manual_fpga.md index 59039f05f1795..8806199b9e6f0 100644 --- a/doc/contributing/fpga/ref_manual_fpga.md +++ b/doc/contributing/fpga/ref_manual_fpga.md @@ -1,6 +1,4 @@ ---- -title: "FPGA Reference Manual" ---- +# FPGA Reference Manual This manual provides additional usage details about the FPGA. Specifically, it provides instructions on SW development flows and testing procedures. diff --git a/doc/contributing/github_notes.md b/doc/contributing/github_notes.md index c94ffc407d75a..d24aae2bd5d91 100644 --- a/doc/contributing/github_notes.md +++ b/doc/contributing/github_notes.md @@ -1,6 +1,4 @@ ---- -title: GitHub Notes ---- +# GitHub Notes The OpenTitan source tree is maintained on GitHub in a [monolithic repository](https://github.com/lowRISC/opentitan) called opentitan. diff --git a/doc/contributing/hw/comportability/README.md b/doc/contributing/hw/comportability/README.md index 7c7b95a0f4e4b..a997f18d40476 100644 --- a/doc/contributing/hw/comportability/README.md +++ b/doc/contributing/hw/comportability/README.md @@ -1,6 +1,4 @@ ---- -title: "Comportability Definition and Specification" ---- +# Comportability Definition and Specification ## Document Goals diff --git a/doc/contributing/hw/design.md b/doc/contributing/hw/design.md index c699c9e25a0f3..14dd0d4c6aa87 100644 --- a/doc/contributing/hw/design.md +++ b/doc/contributing/hw/design.md @@ -1,6 +1,4 @@ ---- -title: "Designing Hardware" ---- +# Designing Hardware This document aims to clarify how to get started with a hardware design within the OpenTitan project. Design in this context nominally refers to a new [Comportable Peripheral](./comportability/README.md) but can include high level constructs like device reset strategy, etc. diff --git a/doc/contributing/hw/methodology.md b/doc/contributing/hw/methodology.md index e62829ca2c42a..050c6ddc511df 100644 --- a/doc/contributing/hw/methodology.md +++ b/doc/contributing/hw/methodology.md @@ -1,6 +1,4 @@ ---- -title: "Design Methodology within OpenTitan" ---- +# Design Methodology within OpenTitan The design methodology within OpenTitan combines the challenges of industry-strength design methodologies with open source ambitions. When in conflict, quality must win, and thus we aim to create a final design product that is equal to the quality required from a full production silicon chip tapeout. diff --git a/doc/contributing/hw/vendor.md b/doc/contributing/hw/vendor.md index 8e332155621a7..ba2943798911c 100644 --- a/doc/contributing/hw/vendor.md +++ b/doc/contributing/hw/vendor.md @@ -1,6 +1,4 @@ ---- -title: Work with hardware code in external repositories ---- +# Work with hardware code in external repositories OpenTitan is not a closed ecosystem: we incorporate code from third parties, and we split out pieces of our code to reach a wider audience. In both cases, we need to import and use code from external repositories in our OpenTitan code base. diff --git a/doc/contributing/style_guides/README.md b/doc/contributing/style_guides/README.md index 0bf80f94dda45..adae30980e96a 100644 --- a/doc/contributing/style_guides/README.md +++ b/doc/contributing/style_guides/README.md @@ -1,6 +1,4 @@ ---- -title: "Style Guides" ---- +# Style Guides OpenTitan's CI enforces what it can of the following style guides to avoid conflict, toil and confusion. However, code reviewers are also responsible for enforcing coding style guidelines and best practices. diff --git a/doc/contributing/style_guides/asm_coding_style.md b/doc/contributing/style_guides/asm_coding_style.md index daf16f90233e7..2d768fca4bf24 100644 --- a/doc/contributing/style_guides/asm_coding_style.md +++ b/doc/contributing/style_guides/asm_coding_style.md @@ -1,6 +1,4 @@ ---- -title: "RISC-V Assembly Style Guide" ---- +# RISC-V Assembly Style Guide ## Basics diff --git a/doc/contributing/style_guides/c_cpp_coding_style.md b/doc/contributing/style_guides/c_cpp_coding_style.md index 00e992534bdf9..aa9c1101c1562 100644 --- a/doc/contributing/style_guides/c_cpp_coding_style.md +++ b/doc/contributing/style_guides/c_cpp_coding_style.md @@ -1,6 +1,4 @@ ---- -title: "C and C++ Coding Style Guide" ---- +# C and C++ Coding Style Guide ## Basics diff --git a/doc/contributing/style_guides/guidance_for_volatile.md b/doc/contributing/style_guides/guidance_for_volatile.md index 8d5635d5176df..a2e5264c1e659 100644 --- a/doc/contributing/style_guides/guidance_for_volatile.md +++ b/doc/contributing/style_guides/guidance_for_volatile.md @@ -1,6 +1,4 @@ ---- -title: "Guidance for `volatile` in OpenTitan Silicon Creator Code" ---- +# Guidance for `volatile` in OpenTitan Silicon Creator Code ## TL;DR diff --git a/doc/contributing/style_guides/hjson_usage_style.md b/doc/contributing/style_guides/hjson_usage_style.md index 9d4f1a80686a6..9212bfe9f323a 100644 --- a/doc/contributing/style_guides/hjson_usage_style.md +++ b/doc/contributing/style_guides/hjson_usage_style.md @@ -1,6 +1,4 @@ ---- -title: "Hjson Usage and Style Guide" ---- +# Hjson Usage and Style Guide ## Basics diff --git a/doc/contributing/style_guides/markdown_usage_style.md b/doc/contributing/style_guides/markdown_usage_style.md index 2df274af8cd95..4931ed03dd335 100644 --- a/doc/contributing/style_guides/markdown_usage_style.md +++ b/doc/contributing/style_guides/markdown_usage_style.md @@ -1,6 +1,4 @@ ---- -title: "Markdown Usage and Style Guide" ---- +# Markdown Usage and Style Guide ## Basics diff --git a/doc/contributing/style_guides/otbn_style_guide.md b/doc/contributing/style_guides/otbn_style_guide.md index 3f133e2b9f9fd..8a6d12c24378c 100644 --- a/doc/contributing/style_guides/otbn_style_guide.md +++ b/doc/contributing/style_guides/otbn_style_guide.md @@ -1,6 +1,4 @@ ---- -title: "OTBN Assembly Style Guide" ---- +# OTBN Assembly Style Guide Where possible, OTBN assembly should follow the same principles as the [RISC-V assembly style guide](./asm_coding_style.md). This guide describes additional OTBN-specific guidelines, and places where OTBN assembly can or should diverge from the RISC-V style guidelines. diff --git a/doc/contributing/style_guides/python_coding_style.md b/doc/contributing/style_guides/python_coding_style.md index e2944591143db..15dda01153078 100644 --- a/doc/contributing/style_guides/python_coding_style.md +++ b/doc/contributing/style_guides/python_coding_style.md @@ -1,6 +1,4 @@ ---- -title: "Python Coding Style Guide" ---- +# Python Coding Style Guide ## Basics diff --git a/doc/contributing/sw/device_interface_functions.md b/doc/contributing/sw/device_interface_functions.md index 8f5eb4c362f46..45ecddf0108e5 100644 --- a/doc/contributing/sw/device_interface_functions.md +++ b/doc/contributing/sw/device_interface_functions.md @@ -1,6 +1,4 @@ ---- -title: "Device Interface Functions (DIFs)" ---- +# Device Interface Functions (DIFs) ## Motivation diff --git a/doc/contributing/sw/otbn_sw.md b/doc/contributing/sw/otbn_sw.md index 6640d391888f8..cf17e5a00eb6b 100644 --- a/doc/contributing/sw/otbn_sw.md +++ b/doc/contributing/sw/otbn_sw.md @@ -1,6 +1,4 @@ ---- -title: "Writing and building software for OTBN" ---- +# Writing and building software for OTBN OTBN is the OpenTitan Big Number accelerator and this document describes how to write and build software for it. The [OTBN reference manual](../../../hw/ip/otbn/README.md) describes the hardware and associated ISA. diff --git a/doc/contributing/system_list.md b/doc/contributing/system_list.md index 9744c853953e3..27c2d9aa57406 100644 --- a/doc/contributing/system_list.md +++ b/doc/contributing/system_list.md @@ -1,6 +1,4 @@ ---- -title: "List of Top-Level Designs" ---- +# List of Top-Level Designs This page lists all top-level designs and their targets that are contained within this repository. Click on the design name to get more information about the design. diff --git a/doc/guides/getting_started/src/README.md b/doc/guides/getting_started/src/README.md index 5fb9b8b01c241..77f90aa7905ba 100644 --- a/doc/guides/getting_started/src/README.md +++ b/doc/guides/getting_started/src/README.md @@ -1,9 +1,4 @@ ---- -title: "Getting Started" -aliases: - - /doc/ug/getting_started - - /doc/ug/install_instructions ---- +# Getting Started Welcome! This guide will help you get OpenTitan up and running. diff --git a/doc/guides/getting_started/src/build_docs.md b/doc/guides/getting_started/src/build_docs.md index 7a16260107c09..b882d0d91577c 100644 --- a/doc/guides/getting_started/src/build_docs.md +++ b/doc/guides/getting_started/src/build_docs.md @@ -1,6 +1,4 @@ ---- -title: "Building documentation" ---- +# Building documentation The documentation for OpenTitan is available [online](https://docs.opentitan.org). The creation of documentation is mainly based around the conversion from Markdown to HTML files with [Hugo](https://gohugo.io/). diff --git a/doc/guides/getting_started/src/build_sw.md b/doc/guides/getting_started/src/build_sw.md index 0fb2a489f5531..510b96a125390 100644 --- a/doc/guides/getting_started/src/build_sw.md +++ b/doc/guides/getting_started/src/build_sw.md @@ -1,8 +1,4 @@ ---- -title: Building (and Testing) Software -aliases: - - /doc/ug/getting_started_build_sw ---- +# Building (and Testing) Software _Before following this guide, make sure you have read the_: * main [Getting Started](README.md) instructions, diff --git a/doc/guides/getting_started/src/install_openocd.md b/doc/guides/getting_started/src/install_openocd.md index 4a085940df9b0..0a2e2e1b5c4d9 100644 --- a/doc/guides/getting_started/src/install_openocd.md +++ b/doc/guides/getting_started/src/install_openocd.md @@ -1,6 +1,4 @@ ---- -title: Install OpenOCD ---- +# Install OpenOCD OpenOCD is a tool to connect with the target chip over JTAG and similar transports. It also provides a GDB server which is an "intermediate" when debugging software on the chip with GDB. diff --git a/doc/guides/getting_started/src/install_vivado/README.md b/doc/guides/getting_started/src/install_vivado/README.md index e1a14e4550d8e..db7ed0d13b4a7 100644 --- a/doc/guides/getting_started/src/install_vivado/README.md +++ b/doc/guides/getting_started/src/install_vivado/README.md @@ -1,6 +1,4 @@ ---- -title: Install Vivado ---- +# Install Vivado Generating a bitstream for Xilinx devices requires a [Vivado](https://www.xilinx.com/products/design-tools/vivado.html) installation. diff --git a/doc/guides/getting_started/src/setup_dv.md b/doc/guides/getting_started/src/setup_dv.md index 354335a7e183a..2bc031467d854 100644 --- a/doc/guides/getting_started/src/setup_dv.md +++ b/doc/guides/getting_started/src/setup_dv.md @@ -1,8 +1,4 @@ ---- -title: "Design Verification Setup" -aliases: - - /doc/ug/getting_started_dv ---- +# Design Verification Setup _Before following this guide, make sure you've followed the [dependency installation and software build instructions](https://opentitan.org/book/doc/guides/getting_started/)._ diff --git a/doc/guides/getting_started/src/setup_formal.md b/doc/guides/getting_started/src/setup_formal.md index c14d7d1120d2d..d9b7c574871b1 100644 --- a/doc/guides/getting_started/src/setup_formal.md +++ b/doc/guides/getting_started/src/setup_formal.md @@ -1,8 +1,4 @@ ---- -title: "Formal Verification Setup" -aliases: - - /doc/ug/getting_started_formal ---- +# Formal Verification Setup _Before following this guide, make sure you've followed the [dependency installation and software build instructions](README.md)._ diff --git a/doc/guides/getting_started/src/setup_fpga.md b/doc/guides/getting_started/src/setup_fpga.md index c55f1e34838a2..5d6d113b27c4f 100644 --- a/doc/guides/getting_started/src/setup_fpga.md +++ b/doc/guides/getting_started/src/setup_fpga.md @@ -1,8 +1,4 @@ ---- -title: "FPGA Setup" -aliases: - - /doc/ug/getting_started_fpga ---- +# FPGA Setup _Before following this guide, make sure you've followed the [dependency installation and software build instructions](README.md)._ diff --git a/doc/guides/getting_started/src/setup_verilator.md b/doc/guides/getting_started/src/setup_verilator.md index 91291f27ee39f..bc0368c38b2f9 100644 --- a/doc/guides/getting_started/src/setup_verilator.md +++ b/doc/guides/getting_started/src/setup_verilator.md @@ -1,8 +1,4 @@ ---- -title: Verilator Setup -aliases: - - /doc/ug/getting_started_verilator ---- +# Verilator Setup _Before following this guide, make sure you've followed the [dependency installation instructions](README.md)._ diff --git a/doc/introduction.md b/doc/introduction.md index 24ec2fcf30ea9..a82a16b77e2f9 100644 --- a/doc/introduction.md +++ b/doc/introduction.md @@ -1,6 +1,4 @@ ---- -title: "OpenTitan" ---- +# OpenTitan ## Introduction to OpenTitan diff --git a/doc/project_governance/README.md b/doc/project_governance/README.md index 4ef2acc29f480..5c0ac231d21e4 100644 --- a/doc/project_governance/README.md +++ b/doc/project_governance/README.md @@ -1,6 +1,4 @@ ---- -title: "Introduction to the OpenTitan Project" ---- +# Introduction to the OpenTitan Project OpenTitan is a collaborative hardware and software development program with contributors from many organizations. This area gives some more information about how the project itself is organized and how to contribute. diff --git a/doc/project_governance/checklist/README.md b/doc/project_governance/checklist/README.md index d2fb80ea527a1..a45a9ba4179d2 100644 --- a/doc/project_governance/checklist/README.md +++ b/doc/project_governance/checklist/README.md @@ -1,6 +1,4 @@ ---- -title: "Signoff Checklist" ---- +# Signoff Checklist This document explains the recommended checklist items to review when transitioning from one [Development Stage](../development_stages.md) to another, for design, verification, and [software device interface function (DIF)](../../contributing/sw/device_interface_functions.md) stages. It is expected that the items in each stage (D1, V1, S1, etc) are completed. diff --git a/doc/project_governance/committers.md b/doc/project_governance/committers.md index ffee7b5cc80ce..658cd15acbc03 100644 --- a/doc/project_governance/committers.md +++ b/doc/project_governance/committers.md @@ -1,6 +1,4 @@ ---- -title: "Committers" ---- +# Committers Committers are individuals with repository write access. While everyone can and is encouraged to contribute by reviewing code, committers are responsible for final approval and merge. diff --git a/doc/project_governance/development_stages.md b/doc/project_governance/development_stages.md index 01d4ad5db8dfa..0b99c8e3b5496 100644 --- a/doc/project_governance/development_stages.md +++ b/doc/project_governance/development_stages.md @@ -1,7 +1,4 @@ ---- -aliases: [/doc/project/hw_stages/] -title: OpenTitan Hardware Development Stages ---- +# OpenTitan Hardware Development Stages ## Document Goals diff --git a/doc/project_governance/rfc_process.md b/doc/project_governance/rfc_process.md index 168c4b8a4b1f9..7071300496f1a 100644 --- a/doc/project_governance/rfc_process.md +++ b/doc/project_governance/rfc_process.md @@ -1,6 +1,4 @@ ---- -title: OpenTitan RFC Process ---- +# OpenTitan RFC Process ## Introduction diff --git a/doc/project_governance/technical_committee.md b/doc/project_governance/technical_committee.md index 1a5ea9d41d322..ab70209fa02ab 100644 --- a/doc/project_governance/technical_committee.md +++ b/doc/project_governance/technical_committee.md @@ -1,6 +1,4 @@ ---- -title: "OpenTitan Technical Committee" ---- +# OpenTitan Technical Committee The OpenTitan Technical Committee is part of the [OpenTitan governance structure](./README.md) and the definitive description of its operations and responsibilities are stated in the [OpenTitan Technical Charter](https://static.opentitan.org/technical-charter.pdf). Key responsibilities defined in that document include: diff --git a/doc/rust_for_c_devs.md b/doc/rust_for_c_devs.md index c8c5acd624ee6..6450f188fc17a 100644 --- a/doc/rust_for_c_devs.md +++ b/doc/rust_for_c_devs.md @@ -1,6 +1,4 @@ ---- -title: "Rust for Embedded C Programmers" ---- +# Rust for Embedded C Programmers ## Foreword diff --git a/doc/security/README.md b/doc/security/README.md index 1584bb6564266..3bcd51ac8f61a 100644 --- a/doc/security/README.md +++ b/doc/security/README.md @@ -1,7 +1,4 @@ ---- -title: "Security" -url: "/security/" ---- +# Security ## Overview diff --git a/doc/security/implementation_guidelines/README.md b/doc/security/implementation_guidelines/README.md index ca03df7007d0c..db2af7f2814f3 100644 --- a/doc/security/implementation_guidelines/README.md +++ b/doc/security/implementation_guidelines/README.md @@ -1,5 +1,3 @@ ---- -title: Implementation Guidelines ---- +# Implementation Guidelines {{% sectionContent %}} diff --git a/doc/security/implementation_guidelines/hardware/README.md b/doc/security/implementation_guidelines/hardware/README.md index 6130ae74761b7..96a49b7bb0b5e 100644 --- a/doc/security/implementation_guidelines/hardware/README.md +++ b/doc/security/implementation_guidelines/hardware/README.md @@ -1,6 +1,4 @@ ---- -title: "Secure Hardware Design Guidelines" ---- +# Secure Hardware Design Guidelines ## Overview diff --git a/doc/security/logical_security_model/README.md b/doc/security/logical_security_model/README.md index 09086f883d177..e01c3d43862d1 100644 --- a/doc/security/logical_security_model/README.md +++ b/doc/security/logical_security_model/README.md @@ -1,6 +1,4 @@ ---- -title: "OpenTitan Logical Security Model" ---- +# OpenTitan Logical Security Model ## Overview diff --git a/doc/security/specs/README.md b/doc/security/specs/README.md index 105ecfe530c59..f45f5832389ee 100644 --- a/doc/security/specs/README.md +++ b/doc/security/specs/README.md @@ -1,6 +1,4 @@ ---- -title: "OpenTitan Security Model Specification" ---- +# OpenTitan Security Model Specification The current version of the security model targets discrete silicon implementations of OpenTitan. The architecture for an integrated IP solution diff --git a/doc/security/specs/attestation/README.md b/doc/security/specs/attestation/README.md index e8a184daac86e..fe6468d59f9c3 100644 --- a/doc/security/specs/attestation/README.md +++ b/doc/security/specs/attestation/README.md @@ -1,6 +1,4 @@ ---- -title: "Device Attestation" ---- +# Device Attestation ## Overview diff --git a/doc/security/specs/device_life_cycle/README.md b/doc/security/specs/device_life_cycle/README.md index 4279920813f3c..96346725e4513 100644 --- a/doc/security/specs/device_life_cycle/README.md +++ b/doc/security/specs/device_life_cycle/README.md @@ -1,6 +1,4 @@ ---- -title: "Device Life Cycle" ---- +# Device Life Cycle ## Overview diff --git a/doc/security/specs/device_provisioning/README.md b/doc/security/specs/device_provisioning/README.md index 09bc725f2a746..a84e856f7b360 100644 --- a/doc/security/specs/device_provisioning/README.md +++ b/doc/security/specs/device_provisioning/README.md @@ -1,6 +1,4 @@ ---- -title: "Device Provisioning" ---- +# Device Provisioning

Status: Pre-RFC diff --git a/doc/security/specs/firmware_update/README.md b/doc/security/specs/firmware_update/README.md index 562e84b99c16a..80dbc29b7c177 100644 --- a/doc/security/specs/firmware_update/README.md +++ b/doc/security/specs/firmware_update/README.md @@ -1,6 +1,4 @@ ---- -title: "Firmware Update" ---- +# Firmware Update

Status: Pre-RFC diff --git a/doc/security/specs/identities_and_root_keys/README.md b/doc/security/specs/identities_and_root_keys/README.md index 18cc68823604c..054dec9c73fd5 100644 --- a/doc/security/specs/identities_and_root_keys/README.md +++ b/doc/security/specs/identities_and_root_keys/README.md @@ -1,6 +1,4 @@ ---- -title: "Identities and Root Keys" ---- +# Identities and Root Keys ## Overview diff --git a/doc/security/specs/ownership_transfer/README.md b/doc/security/specs/ownership_transfer/README.md index 5d2c349747091..9f33e5754b12d 100644 --- a/doc/security/specs/ownership_transfer/README.md +++ b/doc/security/specs/ownership_transfer/README.md @@ -1,6 +1,4 @@ ---- -title: "Ownership Transfer" ---- +# Ownership Transfer ## Overview diff --git a/doc/security/specs/secure_boot/README.md b/doc/security/specs/secure_boot/README.md index 372493f0d5274..012025bda6c53 100644 --- a/doc/security/specs/secure_boot/README.md +++ b/doc/security/specs/secure_boot/README.md @@ -1,6 +1,4 @@ ---- -title: "Secure Boot" ---- +# Secure Boot

Status: Pre-RFC diff --git a/doc/security/threat_model/README.md b/doc/security/threat_model/README.md index 8c2b0a6f44d67..d4dbc2707c8b5 100644 --- a/doc/security/threat_model/README.md +++ b/doc/security/threat_model/README.md @@ -1,6 +1,4 @@ ---- -title: Lightweight Threat Model ---- +# Lightweight Threat Model This threat model aims to identify in-scope design assets, attacker profiles, attack methods and attack surfaces. This is used to produce security diff --git a/doc/use_cases/README.md b/doc/use_cases/README.md index 56f20167e05f7..79950877934a8 100644 --- a/doc/use_cases/README.md +++ b/doc/use_cases/README.md @@ -1,6 +1,4 @@ ---- -title: "Use Cases" ---- +# Use Cases ## Overview diff --git a/doc/use_cases/platform_integrity_module/README.md b/doc/use_cases/platform_integrity_module/README.md index 630078dd47c2d..385076b742383 100644 --- a/doc/use_cases/platform_integrity_module/README.md +++ b/doc/use_cases/platform_integrity_module/README.md @@ -1,6 +1,4 @@ ---- -title: "Platform Integrity Module" ---- +# Platform Integrity Module An OpenTitan IC used as a Platform Integrity Module interposes between a platform's boot flash and its main boot devices such as the Baseboard Management diff --git a/doc/use_cases/tpm/README.md b/doc/use_cases/tpm/README.md index c2ccb4a1af463..ada6a78710d45 100644 --- a/doc/use_cases/tpm/README.md +++ b/doc/use_cases/tpm/README.md @@ -1,6 +1,4 @@ ---- -title: "Trusted Platform Module - TPM" ---- +# Trusted Platform Module - TPM ## Overview diff --git a/doc/use_cases/u2f/README.md b/doc/use_cases/u2f/README.md index eb2eb2dc38576..ad471ed8a8900 100644 --- a/doc/use_cases/u2f/README.md +++ b/doc/use_cases/u2f/README.md @@ -1,6 +1,4 @@ ---- -title: "Universal 2nd-Factor Security Key" ---- +# Universal 2nd-Factor Security Key When used as a security key, OpenTitan implements the Universal 2nd Factor (U2F) authentication standard, using a Universal Serial Bus (USB) 1.1 interface to diff --git a/hw/README.md b/hw/README.md index fed27c905b6f8..a5336f2c23dcd 100644 --- a/hw/README.md +++ b/hw/README.md @@ -1,7 +1,4 @@ ---- -title: "Hardware" -aliases: [/doc/project/hw_dashboard/] ---- +# Hardware This page serves as the landing spot for all hardware development within the OpenTitan project. diff --git a/hw/dv/README.md b/hw/dv/README.md index 7a363f198bf28..10af998521196 100644 --- a/hw/dv/README.md +++ b/hw/dv/README.md @@ -1,6 +1,4 @@ ---- -title: "Common Design Verification Collateral" ---- +# Common Design Verification Collateral The documentation is split into SystemVerilog reference and tools. {{% sectionContent type="section" depth="1" %}} diff --git a/hw/dv/doc/dv_doc_template.md b/hw/dv/doc/dv_doc_template.md index 24aabd82bd0fd..e5ce44c974d4d 100644 --- a/hw/dv/doc/dv_doc_template.md +++ b/hw/dv/doc/dv_doc_template.md @@ -1,7 +1,4 @@ ---- -title: "FOO DV document" -draft: true ---- +# FOO DV document diff --git a/util/fpvgen/README.md b/util/fpvgen/README.md index 550f9fccc8980..9dbfe237b3412 100644 --- a/util/fpvgen/README.md +++ b/util/fpvgen/README.md @@ -1,6 +1,4 @@ ---- -title: "Fpvgen: Initial FPV testbench generation tool" ---- +# Fpvgen: Initial FPV testbench generation tool # Overview diff --git a/util/i2csvg/smbus/SMBus.md b/util/i2csvg/smbus/SMBus.md index 3af33882ca763..6e044bd46276f 100644 --- a/util/i2csvg/smbus/SMBus.md +++ b/util/i2csvg/smbus/SMBus.md @@ -1,6 +1,4 @@ ---- -title: Using I2C host for SMBus commands ---- +# Using I2C host for SMBus commands The I2C host can generate all the SMBus commands listed in the Rev 3.0 SMBus specification. diff --git a/util/ipgen/README.md b/util/ipgen/README.md index fb36b9e63fef1..69e35a0c0f114 100644 --- a/util/ipgen/README.md +++ b/util/ipgen/README.md @@ -1,6 +1,4 @@ ---- -title: "Ipgen: Generate IP blocks from IP templates" ---- +# Ipgen: Generate IP blocks from IP templates Ipgen is a tool to produce IP blocks from IP templates. diff --git a/util/reggen/README.md b/util/reggen/README.md index e3b385efb3f2d..1c84eab33c245 100644 --- a/util/reggen/README.md +++ b/util/reggen/README.md @@ -1,6 +1,4 @@ ---- -title: "Register Tool" ---- +# Register Tool The register tool is used to construct register documentation, register RTL and header files. It is either used stand-alone or by being invoked as part of Markdown processing. diff --git a/util/reggen/doc/setup_and_use.md b/util/reggen/doc/setup_and_use.md index 028eecf9a19c5..8281b384f21f6 100644 --- a/util/reggen/doc/setup_and_use.md +++ b/util/reggen/doc/setup_and_use.md @@ -1,6 +1,4 @@ ---- -title: "Register generator `reggen` and `regtool`" ---- +# Register generator `reggen` and `regtool` The utility script `regtool.py` and collateral under `reggen` are Python tools to read register descriptions in Hjson and generate various output diff --git a/util/rewrite_frontmatter.py b/util/rewrite_frontmatter.py new file mode 100644 index 0000000000000..e19a90c600f9b --- /dev/null +++ b/util/rewrite_frontmatter.py @@ -0,0 +1,61 @@ +#!/usr/bin/env python3 +# Copyright lowRISC contributors. +# Licensed under the Apache License, Version 2.0, see LICENSE for details. +# SPDX-License-Identifier: Apache-2.0 +"""Replaces front-matter with a standard markdown title, ignoring all other fields""" + +from pathlib import Path +import argparse + + +parser = argparse.ArgumentParser() +parser.add_argument("root_doc", + help = "path to the root of documentation") +g_args = parser.parse_args() + +g_root_doc = Path(g_args.root_doc).resolve() +# if root doc is a link to a book.toml file, just open this one +assert g_root_doc.is_dir(), "you must give a path to the root of the repo" + + +def apply_to_md_files(path, fn): + """ + List all files under the directory of the book and call a function on each one + """ + def apply_rec(path): + for child in path.iterdir(): + if child.name.endswith(".md"): + fn(child) + if child.is_dir(): + apply_rec(child.resolve()) + apply_rec(path) + + +def rewrite_title(path): + relpath = path.relative_to(g_root_doc) + # don't touch files in site/, sw/vendor/, hw/vendor/ + if relpath.parts[0] == "site" or relpath.parts[0:2] in (('sw', 'vendor'), ('hw', 'vendor')): + return + with path.open() as f: + lines = [] + for line in f: + lines.append(line) + # it must start with --- + if len(lines) == 0 or not lines[0].startswith("---"): + return # ignore + line_nr = 1 + title = None + while not lines[line_nr].startswith("---"): + this_line = lines[line_nr] + line_nr += 1 + if this_line.startswith("title:"): + title = this_line[6:].strip() + # remove quotes if any + if title[0] == '"' and title[-1] == '"': + title = title[1:-1] + new_lines = [f"# {title}\n"] + lines = new_lines + lines[line_nr + 1:] + path.write_text("".join(lines)) + + +apply_to_md_files(g_root_doc, rewrite_title) diff --git a/util/tlgen/README.md b/util/tlgen/README.md index f795a59e6af98..c05027578ee10 100644 --- a/util/tlgen/README.md +++ b/util/tlgen/README.md @@ -1,6 +1,4 @@ ---- -title: "Crossbar Generation Tool" ---- +# Crossbar Generation Tool The crossbar tool `tlgen.py` is used to build the TL-UL crossbar RTL. It can be used standalone or invoked as part of top module generation process (details of top generation forthcoming). diff --git a/util/topgen/README.md b/util/topgen/README.md index 395d43ecb8400..b01965692ff9c 100644 --- a/util/topgen/README.md +++ b/util/topgen/README.md @@ -1,6 +1,4 @@ ---- -title: "Top Generation Tool" ---- +# Top Generation Tool The top generation tool `topgen.py` is used to build top specific modules for a specific OpenTitan design - for example [`top_earlgrey`](https://github.com/lowRISC/opentitan/tree/master/hw/top_earlgrey). Currently, as part of this generation process, the following top specific modules are created diff --git a/util/uvmdvgen/README.md b/util/uvmdvgen/README.md index 62c51f73ac3d1..9072c83b79e01 100644 --- a/util/uvmdvgen/README.md +++ b/util/uvmdvgen/README.md @@ -1,6 +1,4 @@ ---- -title: "Uvmdvgen: Initial testbench auto-generation tool" ---- +# Uvmdvgen: Initial testbench auto-generation tool `uvmdvgen` is a Python based tool to generate the boilerplate code for a UVM agent as well as the complete UVM testbench for a given DUT. The tool generates