blob: 796f5d096f5c03074b17b9a89531676c3988d81b [file] [view] [edit]
(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 Markdown. They are generated at build time by
`libc/utils/docgen/docgen.py`, which:
1. Reads YAML function and macro definitions from `libc/utils/docgen/<header>.yaml`.
2. Checks implementation status against platform `entrypoints.txt` files (excluding `TODO` stubs).
3. Checks `libc/include/llvm-libc-macros/` and `libc/include/<header>.yaml` for macro definitions.
4. Emits a MyST Markdown page with styled HTML tables 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 `.md` 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`.