llvm-tms34010/libc/docs/dev/building_docs.md

(building_docs)=

Building the Documentation

This page explains how to build the LLVM-libc HTML documentation locally so you can preview changes before submitting a patch.

Prerequisites

The LLVM documentation build uses Sphinx. The key packages required are:

• sphinx — the documentation generator
• furo — the theme used by LLVM-libc
• myst-parser — Markdown support alongside RST
• sphinx-reredirects — handles page redirect entries in conf.py

On Debian/Ubuntu, all required packages are available via apt:

sudo apt-get install python3-sphinx python3-myst-parser \
  python3-sphinx-reredirects furo

On other systems, install everything from the shared requirements file:

pip install -r llvm/docs/requirements.txt

CMake Configuration

Enable the Sphinx documentation build by adding these flags to your CMake invocation:

cmake ../runtimes \
  -DLLVM_ENABLE_RUNTIMES="libc" \
  -DLLVM_ENABLE_SPHINX=ON \
  -DLIBC_INCLUDE_DOCS=ON \
  ...

The LLVM_ENABLE_SPHINX=ON flag enables Sphinx globally for all LLVM subprojects. LIBC_INCLUDE_DOCS=ON is specific to libc and tells CMake to register the libc doc targets.

Building

Once configured, build the HTML docs with:

ninja docs-libc-html

The output is written to <build-dir>/tools/libc/docs/html/. Open index.html in a browser to view the site.

Header Status Pages (Auto-generated)

The per-header implementation status pages under docs/headers/ are not hand-written RST. They are generated at build time by libc/utils/docgen/docgen.py, which:

1. Reads YAML function definitions from libc/src/<header>/*.yaml.
2. Scans libc/src/<header>/ for .cpp implementation files.
3. Checks libc/include/llvm-libc-macros/ for macro #define entries.
4. Emits an RST list-table showing each symbol's implementation status, C standard section, and POSIX link.

If you add a new function and regenerate, these pages update automatically. Do not hand-edit the generated RST files in docs/headers/ — your changes will be overwritten the next time the docs are built.

Troubleshooting

Extension error: Could not import extension myst_parser

On Debian/Ubuntu: sudo apt-get install python3-myst-parser. Otherwise: pip install -r llvm/docs/requirements.txt.

WARNING: document isn't included in any toctree

A new RST/Markdown file needs a toctree entry. Add it to the appropriate index.rst or its parent toctree.

Extension error: No module named 'sphinx_reredirects'

Same fix: pip install -r llvm/docs/requirements.txt.