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)
41 lines
1.3 KiB
ReStructuredText
41 lines
1.3 KiB
ReStructuredText
.. ---------------------------------------------------------------------------
|
|
Shared substitution definitions for implementation-status badges.
|
|
This file is excluded from the toctree (via exclude_patterns in conf.py).
|
|
Include it in any RST page that needs status badges:
|
|
|
|
.. include:: /Helpers/Styles.rst (adjust path as needed)
|
|
|
|
Usage::
|
|
|
|
|Complete| — feature/function is fully implemented
|
|
|Partial| — partial implementation (some variants/platforms missing)
|
|
|InProgress| — implementation underway, not yet merged
|
|
|NotStarted| — no implementation exists yet
|
|
|GPUOnly| — implemented on GPU targets only
|
|
|LinuxOnly| — implemented on Linux targets only
|
|
---------------------------------------------------------------------------
|
|
|
|
.. |Complete| raw:: html
|
|
|
|
<span class="badge badge-complete">Complete</span>
|
|
|
|
.. |Partial| raw:: html
|
|
|
|
<span class="badge badge-partial">Partial</span>
|
|
|
|
.. |InProgress| raw:: html
|
|
|
|
<span class="badge badge-inprogress">In Progress</span>
|
|
|
|
.. |NotStarted| raw:: html
|
|
|
|
<span class="badge badge-notstarted">Not Started</span>
|
|
|
|
.. |GPUOnly| raw:: html
|
|
|
|
<span class="badge badge-gpuonly">GPU Only</span>
|
|
|
|
.. |LinuxOnly| raw:: html
|
|
|
|
<span class="badge badge-linuxonly">Linux Only</span>
|