[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 <[email protected]> Co-authored-by: Amaury Pouly <[email protected]>
vrozic · Mar 7, 2023 · f6298b3 · f6298b3
1 parent 544e7a6
commit f6298b3
Show file tree

Hide file tree

Showing 293 changed files with 353 additions and 898 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -1,6 +1,4 @@
----
-title: "OpenTitan"
----
+# OpenTitan
 
 ## Introduction to OpenTitan
 

diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -1,6 +1,4 @@
----
-title: "Device Attestation"
----
+# Device Attestation
 
 ## Overview