| .. _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: | |
| .. code-block:: bash | |
| sudo apt-get install python3-sphinx python3-myst-parser \ | |
| python3-sphinx-reredirects furo | |
| **On other systems**, install everything from the shared requirements file: | |
| .. code-block:: bash | |
| pip install -r llvm/docs/requirements.txt | |
| CMake Configuration | |
| =================== | |
| Enable the Sphinx documentation build by adding these flags to your CMake | |
| invocation: | |
| .. code-block:: 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: | |
| .. code-block:: 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``. |