7030a34403
Switch the libc documentation site from the alabaster theme to Furo,
which provides mobile-friendly layout, a collapsible sidebar with
caption-based section grouping, and built-in "Edit this page" links.
Changes by area:
conf.py
- Switch html_theme to "furo"
- Add myst_parser extension (already in llvm/docs/requirements.txt, used
by LLDB/Clang/LLVM docs) to allow Markdown alongside RST
- Accept both .rst and .md source suffixes
- Configure Furo source_repository/source_branch/source_directory for
"Edit this page" links pointing to GitHub
- Wire _static/copybutton.{js,css} for copy-to-clipboard buttons on code
blocks (no new pip dependency; can migrate to sphinx-copybutton later
once it's in requirements-hashed.txt)
- Exclude plan-docs.md and Helpers/ from Sphinx processing
index.rst
- Rewrite landing page: remove apologetic "not fully complete" note, add
"What Works Today" section with concrete supported use cases, honest
caveat that full C stdlib coverage is still in progress
- Restructure hidden toctrees into five captioned sidebar groups: "Using
LLVM-libc", "Platforms" (GPU/UEFI promoted to top-level),
"Implementation Status", "Development", "Links"
New files
- docs/_static/copybutton.{js,css}: lightweight copy button for code
blocks
- docs/_static/custom.css: add status badge styles (.badge-complete
etc.) for use with Helpers/Styles.rst substitutions in later phases
Prepare for future status badges:
- docs/Helpers/Styles.rst: RST substitution definitions for status
badges (|Complete|, |Partial|, |InProgress|, |NotStarted|, |GPUOnly|,
|LinuxOnly|) — excluded from toctree, available for Phase 5+ pages
- docs/dev/building_docs.rst: new page covering prerequisites (with
Debian apt-first instructions), CMake flags, ninja docs-libc-html, the
docgen auto-generation pipeline, and troubleshooting
Removed
- docs/README.txt: stale file claiming Sphinx 1.1.3, not in any toctree;
superseded by docs/dev/building_docs.rst
Cleanups
- Remove redundant ".. contents:: Table of Contents" directives from 16
RST files (Furo renders its own per-page TOC in the sidebar)
- Remove same directive from libc/Maintainers.rst (pulled into docs via
include)
94 lines
2.8 KiB
ReStructuredText
94 lines
2.8 KiB
ReStructuredText
.. _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``.
|