[libc][docs] Furo theme, new landing page, cleanups (#184303)

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)

libc/Maintainers.rst

@@ -8,10 +8,6 @@ LLVM-libc. The following people are the active maintainers for the project.
 Please reach out to them for code reviews, questions about their area of
 expertise, or other assistance.
 
-.. contents::
-   :depth: 1
-   :local:
-
 Lead Maintainer
 ---------------
 | Michael Jones

libc/docs/Helpers/Styles.rst

@@ -0,0 +1,40 @@
+.. ---------------------------------------------------------------------------
+   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>

libc/docs/README.txt

@@ -1,13 +0,0 @@
-libc Documentation
-==================
-
-The libc documentation is written using the Sphinx documentation generator. It is
-currently tested with Sphinx 1.1.3.
-
-To build the documents into html configure libc with the following cmake options:
-
-  * -DLLVM_ENABLE_SPHINX=ON
-  * -DLIBC_INCLUDE_DOCS=ON
-
-After configuring libc with these options the make rule `docs-libc-html`
-should be available.

libc/docs/_static/copybutton.css

@@ -0,0 +1,39 @@
+/* Copy-to-clipboard button styles */
+div.highlight {
+  position: relative;
+}
+
+button.copybutton {
+  position: absolute;
+  top: 0.4em;
+  right: 0.4em;
+  padding: 0.3em 0.4em;
+  background: var(--color-background-secondary, #f0f0f0);
+  border: 1px solid var(--color-foreground-border, #ccc);
+  border-radius: 4px;
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 0.2s, background 0.15s;
+  line-height: 1;
+  color: var(--color-foreground-secondary, #555);
+}
+
+div.highlight:hover button.copybutton,
+button.copybutton:focus {
+  opacity: 1;
+}
+
+button.copybutton:hover {
+  background: var(--color-background-hover, #e0e0e0);
+}
+
+button.copybutton.copied {
+  color: var(--color-brand-primary, #2980b9);
+  opacity: 1;
+}
+
+button.copybutton svg {
+  display: block;
+  pointer-events: none;
+  fill: currentColor;
+}

libc/docs/_static/copybutton.js

@@ -0,0 +1,56 @@
+// Simple "copy to clipboard" button for code blocks.
+// Adds a button to each <div class="highlight"> block.
+(function () {
+  "use strict";
+
+  function addCopyButton(block) {
+    var button = document.createElement("button");
+    button.className = "copybutton";
+    button.title = "Copy";
+    button.setAttribute("aria-label", "Copy code to clipboard");
+    button.innerHTML =
+      '<svg aria-hidden="true" height="16" viewBox="0 0 16 16" width="16">' +
+      '<path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 ' +
+      "0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 " +
+      "0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z" +
+      '"/><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 ' +
+      "1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 " +
+      ".138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z" +
+      '"/></svg>';
+
+    button.addEventListener("click", function () {
+      var code = block.querySelector("pre").innerText;
+      navigator.clipboard.writeText(code).then(
+        function () {
+          button.classList.add("copied");
+          setTimeout(function () {
+            button.classList.remove("copied");
+          }, 2000);
+        },
+        function () {
+          // Fallback for older browsers
+          var ta = document.createElement("textarea");
+          ta.value = code;
+          ta.style.position = "fixed";
+          ta.style.opacity = "0";
+          document.body.appendChild(ta);
+          ta.focus();
+          ta.select();
+          document.execCommand("copy");
+          document.body.removeChild(ta);
+          button.classList.add("copied");
+          setTimeout(function () {
+            button.classList.remove("copied");
+          }, 2000);
+        }
+      );
+    });
+
+    block.style.position = "relative";
+    block.appendChild(button);
+  }
+
+  document.addEventListener("DOMContentLoaded", function () {
+    document.querySelectorAll("div.highlight").forEach(addCopyButton);
+  });
+})();

libc/docs/_static/custom.css

@@ -112,3 +112,24 @@ div.body {
   max-width: auto;
 }
 }
+
+/* ---------------------------------------------------------------------------
+   Status badges (used via Helpers/Styles.rst substitutions)
+   --------------------------------------------------------------------------- */
+.badge {
+  display: inline-block;
+  padding: 0.15em 0.5em;
+  border-radius: 3px;
+  font-size: 0.8em;
+  font-weight: 600;
+  line-height: 1.4;
+  white-space: nowrap;
+}
+
+.badge-complete    { background: #2ea44f; color: #fff; }
+.badge-partial     { background: #f0883e; color: #fff; }
+.badge-inprogress  { background: #0969da; color: #fff; }
+.badge-notstarted  { background: #6e7781; color: #fff; }
+.badge-gpuonly     { background: #8250df; color: #fff; }
+.badge-linuxonly   { background: #1a7f37; color: #fff; }
+

libc/docs/conf.py

@@ -25,13 +25,18 @@ from datetime import date
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["sphinx.ext.intersphinx", "sphinx.ext.todo", "sphinx_reredirects"]
+extensions = [
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx_reredirects",
+    "myst_parser",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # The suffix of source filenames.
-source_suffix = ".rst"
+source_suffix = [".rst", ".md"]
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
@@ -92,15 +97,16 @@ pygments_style = "friendly"
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 # html_theme = 'haiku'
-html_theme = "alabaster"
+html_theme = "furo"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 html_theme_options = {
-    "font_size": "11pt",
-    # Don't generate any links to GitHub.
-    "github_button": "false",
+    # "Edit this page" links
+    "source_repository": "https://github.com/llvm/llvm-project/",
+    "source_branch": "main",
+    "source_directory": "libc/docs/",
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
@@ -126,7 +132,11 @@ html_title = "The LLVM C Library"
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
-#
+
+# Custom JS/CSS files
+html_js_files = ["copybutton.js"]
+html_css_files = ["copybutton.css"]
+
 # html_context = {
 #    'css_files': [
 #        '_static/libc.css'

libc/docs/dev/building_docs.rst

@@ -0,0 +1,93 @@
+.. _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``.

libc/docs/dev/index.rst

@@ -9,6 +9,7 @@ Navigate to the links below for information on the respective topics:
 .. toctree::
    :maxdepth: 1
 
+   building_docs
    code_style
    source_tree_layout
    entrypoints

libc/docs/dev/undefined_behavior.rst

@@ -2,10 +2,6 @@
 Defining Undefined Behavior
 ===========================
 
-.. contents:: Table of Contents
-   :depth: 2
-   :local:
-
 The C standard leaves behavior undefined or implementation defined in many
 places. Undefined behavior is behavior that the standards leave up to the
 implementation. As an implementation, LLVM's libc must provide a result for any

libc/docs/full_cross_build.rst

@@ -4,10 +4,6 @@
 Full Cross Build
 ================
 
-.. contents:: Table of Contents
-   :depth: 1
-   :local:
-
 .. note::
    Fullbuild requires running headergen, which is a python program that depends on
    pyyaml. The minimum versions are listed on the :ref:`header_generation`

libc/docs/full_host_build.rst

@@ -4,10 +4,6 @@
 Full Host Build
 ===============
 
-.. contents:: Table of Contents
-   :depth: 1
-   :local:
-
 .. note::
    Fullbuild requires running headergen, which is a python program that depends on
    pyyaml. The minimum versions are listed on the :ref:`header_generation`

libc/docs/gpu/building.rst

@@ -4,10 +4,6 @@
 Building libs for GPUs
 ======================
 
-.. contents:: Table of Contents
-  :depth: 4
-  :local:
-
 Building the GPU C library
 ==========================
 

libc/docs/gpu/motivation.rst

@@ -4,10 +4,6 @@
 Motivation and Limitations
 ==========================
 
-.. contents:: Table of Contents
-  :depth: 4
-  :local:
-
 Motivation
 ==========
 

libc/docs/gpu/rpc.rst

@@ -4,10 +4,6 @@
 Remote Procedure Calls
 ======================
 
-.. contents:: Table of Contents
-  :depth: 4
-  :local:
-
 Remote Procedure Call Implementation
 ====================================
 

libc/docs/gpu/support.rst

@@ -6,10 +6,6 @@ Supported Functions
 
 .. include:: ../check.rst
 
-.. contents:: Table of Contents
-  :depth: 4
-  :local:
-
 The following functions and headers are supported at least partially on the
 device. Some functions are implemented fully on the GPU, while others require a
 `remote procedure call <libc_gpu_rpc>`_.

libc/docs/gpu/testing.rst

@@ -10,10 +10,6 @@ Testing the GPU C library
    out of resource errors, or indefinite hangs. limiting the number of threads
    used while testing using ``LIBC_GPU_TEST_JOBS=<N>`` is highly recommended.
 
-.. contents:: Table of Contents
-  :depth: 4
-  :local:
-
 Testing infrastructure
 ======================
 

libc/docs/gpu/using.rst

@@ -4,10 +4,6 @@
 Using libc for GPUs
 ===================
 
-.. contents:: Table of Contents
-  :depth: 4
-  :local:
-
 Using the GPU C library
 =======================
 

libc/docs/headers/math/index.rst

@@ -18,10 +18,6 @@ math.h
   log.rst
 
 
-.. contents:: Table of Contents
-  :depth: 4
-  :local:
-
 Source Locations
 ================
 

libc/docs/index.rst

@@ -2,83 +2,105 @@
 The LLVM C Library
 ==================
 
-.. note::
-  LLVM-libc is not fully complete right now. Some programs may fail to build due
-  to missing functions. If you would like to help us finish LLVM-libc, check
-  out "`Contributing to the libc project <contributing.html>`__" in the sidebar
-  or ask on `discord <https://discord.com/channels/636084430946959380/636732994891284500>`__
-  (`invite link <https://discord.gg/xS7Z362>`__).
+LLVM-libc is a from-scratch implementation of the C standard library, built as
+part of the LLVM project.  It is designed to be **modular** (any piece can be
+used independently), **multiplatform** (Linux, GPU, baremetal embedded, UEFI,
+macOS, Windows), and written in modern C++ for correctness, performance, and
+safety.
 
-Introduction
+What Works Today
+================
+
+LLVM-libc is **actively used in production** for a targeted set of use cases,
+though coverage is still growing and many programs that depend on the full C
+standard library (regex, locale, wide-character I/O, etc.) will not yet compile
+against it:
+
+* **Static-linked Linux servers and containers** — used in production at Google
+  (servers and Pixel Buds) on x86-64 and AArch64.
+* **GPU compute (AMDGPU, NVPTX)** — libc functions available in GPU kernels
+  via LLVM's offloading runtime.  :doc:`GPU docs <gpu/index>`
+* **Baremetal embedded (ARM, RISC-V, AArch64)** — minimal footprint builds
+  for microcontrollers and custom hardware.
+* **UEFI applications** — experimental support for firmware development.
+  :doc:`UEFI docs <uefi/index>`
+* **LLVM ecosystem internals** — libc++ and the offloading runtime consume
+  LLVM-libc directly via :doc:`Hand-in-Hand <hand_in_hand>`.
+* **Toolchain integrations** — pieces of LLVM-libc are used in Android Bionic,
+  Fuchsia, Emscripten, and the ARM embedded toolchain.
+
+Coverage is still growing.  See the :doc:`implementation status <headers/index>`
+pages for per-header detail, and the
+:doc:`platform support <platform_support>` page for OS/architecture coverage.
+
+Getting Started
+===============
+
+If you are new to LLVM-libc, :doc:`getting_started` is the right first stop.
+It covers cloning, building, testing, and verifying your installation in one
+place.
+
+Want to use LLVM-libc *alongside* your system libc instead of replacing it?
+See :doc:`overlay_mode`.
+
+Get Involved
 ============
 
-LLVM-libc is an implementation of the C standard library written in C++ focused
-on embodying three main principles:
+LLVM-libc is an active project and welcomes contributors of all experience
+levels.  See :doc:`contributing` to learn how to help.
 
-- Modular
-- Multiplatform
-- Community Oriented
-
-Our current goal is to support users who want to make libc part of their
-application. This can be through static linking libc into the application, which
-is common for containerized servers or embedded devices. It can also be through
-using the LLVM-libc internal sources as a library, such as through the
-:ref:`Hand-in-Hand interface<hand_in_hand>`.
-
-For more details please watch the talk "`Climbing the ladder of Complete <https://www.youtube.com/watch?v=HtCMCL13Grg>`__ by Michael Jones.".
-
-LLVM-libc is currently used in Google servers, Pixel Buds, and other Google
-projects. Through Project Hand-in-Hand LLVM-libc's code is used in other LLVM
-projects, specifically libc++ and the offloading runtime. There is an
-experiemental config to use LLVM-libc in Emscripten and the ARM embedded
-toolchain. Pieces of LLVM-libc are being used in Bionic (Android's libc) and
-Fuchsia.
+* `Source code <https://github.com/llvm/llvm-project/tree/main/libc>`__
+* `Bug reports <https://github.com/llvm/llvm-project/labels/libc>`__
+* `Discourse <https://discourse.llvm.org/c/runtimes/libc>`__
+* `Discord <https://discord.com/channels/636084430946959380/636732994891284500>`__
+  (`invite <https://discord.gg/xS7Z362>`__)
+* `Buildbot <https://lab.llvm.org/buildbot/#/builders?tags=libc>`__
 
 .. toctree::
    :hidden:
    :maxdepth: 1
-   :caption: Status & Support
+   :caption: Using LLVM-libc
+
+   getting_started
+   overlay_mode
+   full_host_build
+   full_cross_build
+   configure
+   hand_in_hand
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+   :caption: Platforms
+
+   gpu/index.rst
+   uefi/index.rst
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+   :caption: Implementation Status
 
    headers/index.rst
    arch_support
    platform_support
    compiler_support
 
-.. toctree::
-   :hidden:
-   :maxdepth: 1
-   :caption: Simple Usage
-
-   getting_started
-
-.. toctree::
-   :hidden:
-   :maxdepth: 1
-   :caption: Advanced Usage
-
-   full_host_build
-   full_cross_build
-   overlay_mode
-   gpu/index.rst
-   uefi/index.rst
-   configure
-   hand_in_hand
-
 .. toctree::
    :hidden:
    :maxdepth: 1
    :caption: Development
 
-   Maintainers
+   contributing
    build_and_test
    dev/index.rst
    porting
-   contributing
+   Maintainers
 
 .. toctree::
    :hidden:
    :maxdepth: 1
-   :caption: Useful Links
+   :caption: Links
 
    talks
    Source Code <https://github.com/llvm/llvm-project/tree/main/libc>

libc/docs/overlay_mode.rst

@@ -4,10 +4,6 @@
 Overlay Mode
 ============
 
-.. contents:: Table of Contents
-  :depth: 4
-  :local:
-
 One can choose to use LLVM's libc in the overlay mode. In this mode, the link
 order semantics are exploited to pick symbols from ``libllvmlibc.a`` (if they
 are available in ``libllvmlibc.a``) and the rest are picked from the system

libc/docs/porting.rst

@@ -4,10 +4,6 @@
 Bringup on a New OS or Architecture
 =======================================
 
-.. contents:: Table of Contents
-  :depth: 4
-  :local:
-
 Building the libc
 =================
 

libc/docs/uefi/building.rst

@@ -4,10 +4,6 @@
 Building libc for UEFI
 ======================
 
-.. contents:: Table of Contents
-  :depth: 4
-  :local:
-
 Building LLVM libc for UEFI
 ===========================
 

libc/docs/uefi/support.rst

@@ -6,10 +6,6 @@ Supported Functions
 
 .. include:: ../check.rst
 
-.. contents:: Table of Contents
-  :depth: 4
-  :local:
-
 The follow functions and headers are supported at least partially in
 UEFI. Some functions are implemented fully for UEFI.
 

libc/docs/uefi/testing.rst

@@ -4,10 +4,6 @@
 Testing the UEFI C library
 ==========================
 
-.. contents:: Table of Contents
-  :depth: 4
-  :local:
-
 Testing infrastructure
 ======================
 

libc/docs/uefi/using.rst

@@ -4,10 +4,6 @@
 Using libc for UEFI
 ===================
 
-.. contents:: Table of Contents
-  :depth: 4
-  :local:
-
 Using the UEFI C library
 ========================