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](https://www.sphinx-doc.org/).
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:

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

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

```bash
pip install -r llvm/docs/requirements.txt
```

## CMake Configuration

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

```bash
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:

```bash
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`.