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.