[docs] Dynamically generate TOC

[imphil]

The page https://docs.opentitan.org/ has a TOC-like structure in it, as does https://docs.opentitan.org/doc/ug/. But the contents are manually edited and don't reflect all subsections.

Can we auto-generate this content to keep it up-to-date and ensure that all content is actually linked?

[sjgitty]

For this one we should consider whether a true TOC is what we want. It is possibly going to look good but sometimes TOCs look ungainly. Below is what it would look like if we were to render all of the document titles as the TOC entries. Clearly it is very deep (I'm sure we could employ some .skip directives), but also the algorithm to generate this was not obvious (I had to kluge it several times), so not sure what algorithm we would want to use (perhaps there are standard Hugo things we could use here). It also shows that we need to clean up a lot of our document titles which are not self-explanatory. Thoughts?

• Contributing code to the opentitan repository
• OpenTitan
• lowRISC Documentation Overview
  • Introduction to the OpenTitan Project
  • Signoff Checklist
  • Committers
  • Hardware Designs Dashboard
  • OpenTitan Hardware Development Stages
  • OpenTitan RFC Process
  • Reference Manuals
  • RISC-V Assembly Style Guide
  • C and C++ Coding Style Guide
  • Hjson Usage and Style Guide
  • Markdown Usage and Style Guide
  • Python Coding Style Guide
  • FPGA Reference Manual
  • Top Generation Tool
  • util/vendor.py: Vendor-in Components
  • Verilog Coding Style Guide
  • OpenTitan Security Overview
  • User Guides
  • Design Methodology within OpenTitan
  • Directory Structure
  • Design Verification Methodology within OpenTitan
  • Get an FPGA Board
  • Getting Started with an OpenTitan Hardware Design
  • Getting Started with an OpenTitan Design Verification
  • Getting started on FPGAs
  • Getting Started
  • Build Software
  • Getting started with Verilator
  • GitHub Notes
  • Quickstart
  • List of Top-Level Designs
  • Work with hardware code in external repositories
• Hardware Specifications
  • OpenTitan Assertions
  • RTL Linting
  • Top Earlgrey
  • Third-Party/External Code
  • FOO DV Plan
  • DV build and run flow
    • JTAG DPI module for OpenOCD remote_bitbang driver
    • ALERT Agent
    • Common interfaces
    • CSR utilities
    • DV Library Classes
    • README.md
    • I2C DV UVM Agent
    • JTAG DV UVM Agent
    • Mem_bkdr Interface
    • Memory Model
    • README.md
    • SPI UVM Agent
    • test_vectors_pkg.sv
    • TileLink UVM Agent
    • UART Agent
    • USB20 UVM Agent
    • Comportable IP Testbench Architecture
  • RISC-V Platform-Level Interrupt Controller
    • AES HWIP Technical Specification
    • AES Checklist
    • AES Model
    • AES DV Plan
    • Alert Handler Technical Specification
    • Alert Handler Checklist
      • ALERT_HANDLER DV Plan
    • ENTROPY_SRC HWIP Technical Specification
    • Flash Controller HWIP Technical Specification
    • FLASH_CTRL Checklist
    • GPIO HWIP Technical Specification
    • GPIO Checklist
      • GPIO DV Plan
    • HMAC HWIP Technical Specification
    • HMAC Checklist
      • HMAC DV Plan
      • Cryptoc library (SHA, SHA256 and HMAC)
    • I2C HWIP Technical Specification
    • NMI Generator Technical Specification
      • I2C DV Plan
    • Padctrl Technical Specification
    • Padctrl Checklist
    • Pinmux Technical Specification
    • Pinmux Checklist
    • Primitive Component: LFSR
    • Primitive Component: Packer
    • Ibex RISC-V Core Wrapper Technical Specification
    • Ibex Processor Core Checklist
    • RISC-V Debug System Wrapper Technical Specification
    • Interrupt Controller Technical Specification
    • RV_PLIC DV Plan
    • Timer HWIP Technical Specification
    • RV_TIMER Checklist
      • RV_TIMER DV Plan
    • SPI Device HWIP Technical Specification
    • SPI_DEVICE Checklist
      • SPI Device DV Plan
    • Bus Specification
    • TL-UL Protocol Checker
      • TLUL XBAR DV Plan
    • UART HWIP Technical Specification
    • UART Checklist
      • UART DV Plan
    • Simple USB Full Speed Device IP Technical Specification
      • USBDEV DV Plan
    • USB UART HWIP Technical Specification
  • Earl Grey Top Level Specification
  • TOP Earl Grey
    • TL-UL Checklist
  • Git Considerations
  • Credits
  • README.md
    • Ibex simulation Control/Status Registers Testbench
    • Ibex simulation for RISC-V Compliance Testing
    • Ibex Simple System
    • How to Contribute
    • Overview
    • Overview
    • Verilator memory loading support
    • Ibex RISC-V Core SoC Example
    • Yosys/OpenSTA Ibex Synthesis Flow
  • Changelog
  • RISC-V Debug Support for PULP Cores
    • Overview
• OpenTitan Software
  • Work with software code in external repositories
  • Boot ROM Overview
  • Software Tests Readme
    • Building CoreMark
    • Overview
    • libbase, the OpenTitan Standard Library
    • The OpenTitan DIF Library
    • libruntime, the OpenTitan Runtime Library
    • OpenTitan Freestanding C Headers
  • SPI Flash
  • COREMARK® ACCEPTABLE USE AGREEMENT
  • Introduction
    • READM.md
  • Googletest Mocking (gMock) Framework
  • How to become a contributor and submit your own code
  • Google Test
    • Generic Build Instructions
    • gMock Cheat Sheet
    • gMock Cookbook
    • gMock for Dummies {#GMockForDummies}
    • Legacy gMock FAQ {#GMockFaq}
    • The Problem
    • Please Note:
    • Advanced googletest Topics
    • Googletest FAQ
    • Using GoogleTest from various build systems
    • Googletest Primer
    • Googletest Samples {#samples}
    • Please Note:
  • RISC-V Compliance Task Group
    • RISC-V Targets
    • RISC-V Test Suites
    • Overview
• OpenTitan Utilities
  • Docker Container
  • FPGA Splice flow
  • Fpvgen: Initial FPV testbench generation tool
  • i2csvg -- Generate svg pictures of I2C commands from text description
  • Using I2C master for SMBus commands
  • Register generator reggen and regtool
  • Simple SPI Tests
  • Testplanner tool
  • TL-UL Crossbar RTL generator
  • Uvmdvgen: Initial testbench auto-generation tool
  • Wavegen -- Waveform generator in Python
  • FOO DV plan

[imphil]

It's not uncommon to restrict the TOC to certain levels of depth, e.g. 2. That should keep things interesting for the reader.

[sjgitty]

It's not uncommon to restrict the TOC to certain levels of depth, e.g. 2. That should keep things interesting for the reader.

Agreed except much of our interest stuff is buried deep beyond level 2, and some of the level 1 and level 2 stuff is just filler. I guess the compromise is that we force some catch-all documents of said "interesting stuff" at level 2 so that it is found in the TOC, the same way hw/_index.md has a map of all of the hardware specifications.

[sjgitty]

Perhaps the to-do part of this issue is to create what the TOC-level-2 would look like and suggest changes to our current organization where interesting content would otherwise get lost.

[towoe]

Do we still want this? With the "menu" now available on docs.opentitan.org I think it is better to have some hand crafted text guiding to reader to the important parts (if it would be the only content). But I can still try to get some automatically level 2 generated list which can then be added to the end for selected pages.

[imphil]

I'd either still go for it, or significantly reword it to not look like a TOC any more, but a summary of what's coming (as in https://opensocdebug.readthedocs.io/en/latest/). If it looks like a TOC, it should actually be one and not go out of date repeatedly.

[towoe]

Yes, we should not have a TOC which is not up-to-date. Either none at all or auto generated. The summary approach is also nice, should be possible with Hugo if the front matter of the documentation contains the description. I will provide a PR with a suggestion for the automatic one and then we can decide which direction we will pursue.