[libc][docs] reorder docs to be more beginner friendly

[nickdesaulniers]

This commit does a few things, with the intent to make it more straightforward
to potential future users how to get started with llvm-libc. Answers to "What's
the status and how do I use it?" are front and center, "above the fold."

This commit does a few things:

• reorganize the landing page's toctree:
  • start with implementation status, arch support, platform support, and
    compiler support.
  • Then a (new) simple getting started page using full host builds.
  • Then more advanced topics such as host vs cross builds, overlay mode, gpu
    builds and additional configuration options.
• Remove c23 status, the old fullbuild_mode landing page, and usage_modes
  landing pages. c23 status isn't as interesting as I originally thought it
  might. We should point people at full host builds to start, then link to more
  info on cross compilation, or overlay mode as more advanced topics. I assert
  most users starting out won't care about those.

[llvmbot]

@llvm/pr-subscribers-libc

Author: Nick Desaulniers (nickdesaulniers)

Changes

This commit does a few things, with the intent to make it more straightforward
to potential future users how to get started with llvm-libc. Answers to "What's
the status and how do I use it?" are front and center, "above the fold."

This commit does a few things:

• reorganize the landing page's toctree:
  • start with implementation status, arch support, platform support, and
    compiler support.
  • Then a (new) simple getting started page using full host builds.
  • Then more advanced topics such as host vs cross builds, overlay mode, gpu
    builds and additional configuration options.
• Remove c23 status, the old fullbuild_mode landing page, and usage_modes
  landing pages. c23 status isn't as interesting as I originally thought it
  might. We should point people at full host builds to start, then link to more
  info on cross compilation, or overlay mode as more advanced topics. I assert
  most users starting out won't care about those.

---

Full diff: https://github.com/llvm/llvm-project/pull/122376.diff

7 Files Affected:

• (modified) libc/docs/build_and_test.rst (+1-1)
• (removed) libc/docs/c23.rst (-165)
• (removed) libc/docs/fullbuild_mode.rst (-24)
• (added) libc/docs/getting_started.rst (+60)
• (modified) libc/docs/index.rst (+16-16)
• (modified) libc/docs/porting.rst (+2-2)
• (removed) libc/docs/usage_modes.rst (-15)

diff --git a/libc/docs/build_and_test.rst b/libc/docs/build_and_test.rst
index ccd8b5bbee4759..dfdd96531b1f90 100644
--- a/libc/docs/build_and_test.rst
+++ b/libc/docs/build_and_test.rst
@@ -22,7 +22,7 @@ The libc can be built and tested in two different modes:
    static archive will be run with the above command.
 
 #. **The full build mode** - In this mode, the libc is used as the only libc
-   for the user's application. See :ref:`fullbuild_mode` for more details on
+   for the user's application. See :ref:`full_host_build` for more details on
    building and using the libc in this mode. Once configured for a full libc
    build, you can run three kinds of tests:
 
diff --git a/libc/docs/c23.rst b/libc/docs/c23.rst
deleted file mode 100644
index b9a2424307f84b..00000000000000
--- a/libc/docs/c23.rst
+++ /dev/null
@@ -1,165 +0,0 @@
-.. _c23_support:
-
-===========
-C23 Support
-===========
-
-.. include:: check.rst
-.. contents:: Table of Contents
-  :depth: 4
-  :local:
-
----------------------
-Implementation Status
----------------------
-
-(It's helpful to review 'Annex B (Informative) Library Summary' for these.)
-
-
-Additions:
-
-* fenv.h
-
-  * fesetexcept |check|
-  * fetestexceptflag |check|
-  * fegetmode
-  * fesetmode
-* math.h
-
-  * acospi*
-  * asinpi*
-  * atanpi*
-  * atan2pi*
-  * cospi*
-  * sinpi*
-  * tanpi*
-  * exp10*
-  * exp10m1*
-  * exp2m1*
-  * log10p1*
-  * logp1
-  * log2p1*
-  * rsqrt*
-  * __STDC_IEC_60559_DFP__ functions (_Decimal32, _Decimal64, _Decimal128)
-  * compoundn*
-  * totalorder* |check|
-  * totalordermag* |check|
-  * getpayload* |check|
-  * setpayload* |check|
-  * setpayloadsig* |check|
-  * iscannonical
-  * issignaling
-  * issubnormal
-  * iszero
-  * llogb* |check|
-  * pown*
-  * powr*
-  * rootn*
-  * roundeven* |check|
-  * fromfp* |check|
-  * ufromfp* |check|
-  * fromfpx* |check|
-  * ufromfpx* |check|
-  * nextup* |check|
-  * nextdown* |check|
-  * canonicalize* |check|
-  * fmaximum* |check|
-  * fminimum* |check|
-  * fmaximum_mag* |check|
-  * fminimum_mag* |check|
-  * fmaximum_num* |check|
-  * fminimum_num* |check|
-  * fmaximum_mag_num* |check|
-  * fminimum_mag_num* |check|
-  * fadd*
-  * fsub*
-  * fmul*
-  * fdiv*
-  * ffma*
-  * dfmal
-  * fsqrt*
-  * dsqrtl
-* stdbit.h (New header)    |check|
-* stdckdint.h (New header) |check|
-* stddef.h
-
-  * unreachable
-* stdlib.h
-
-  * strfromd
-  * strfromf
-  * strfroml
-  * free_sized
-  * free_aligned_sized
-  * memalignment
-* string.h
-
-  * memset_explicit |check|
-  * memccpy
-  * strdup
-  * strndup
-* tgmath.h
-
-  * acospi
-  * asinpi
-  * atan2pi
-  * atanpi
-  * compoundn
-  * cospi
-  * erf
-  * exp10m1
-  * exp10
-  * exp2m1
-  * fmaximum
-  * fmaximum_mag
-  * fmaximum_num
-  * fmaximum_mag_num
-  * fminimum
-  * fminimum_mag
-  * fminimum_num
-  * fminimum_mag_num
-  * fromfpx
-  * fromfp
-  * llogb
-  * log10p1
-  * log2p1
-  * logp1
-  * nextdown
-  * nextup
-  * pown
-  * powr
-  * rootn
-  * roundeven
-  * rsqrt
-  * scalbn
-  * sinpi
-  * tanpi
-  * ufromfpx
-  * ufromfp
-  * fadd
-  * dadd
-  * fsub
-  * dsub
-  * fmul
-  * dmul
-  * fdiv
-  * ddiv
-  * ffma
-  * dfma
-  * fsqrt
-  * dsqrt
-* time.h
-
-  * gmtime_r
-  * localtime_r
-  * timegm
-  * timespec_getres
-  * strftime conversion specifiers
-
-    * 0b
-    * 0B
-* uchar.h
-
-  * mbrtoc8
-  * c8rtomb
-  * char*_t |check|
diff --git a/libc/docs/fullbuild_mode.rst b/libc/docs/fullbuild_mode.rst
deleted file mode 100644
index d5c62172dac8e7..00000000000000
--- a/libc/docs/fullbuild_mode.rst
+++ /dev/null
@@ -1,24 +0,0 @@
-.. _fullbuild_mode:
-
-==============
-Fullbuild Mode
-==============
-
-.. note:: 
-   Fullbuild requires running headergen, which is a python program that depends on
-   pyyaml. The minimum versions are listed on the :ref:`header_generation`
-   page, as well as additional information.
-
-The *fullbuild* mode of LLVM's libc is the mode in which it is to be used as
-the only libc (as opposed to the :ref:`overlay_mode` in which it is used along
-with the system libc.) In order to use it as the only libc, one will have to
-build and install not only the static archives like ``libc.a`` from LLVM's libc,
-but also the start-up objects like ``crt1.o`` and the public headers.
-
-The full libc build can be of two types:
-
-.. toctree::
-   :maxdepth: 1
-
-   full_host_build
-   full_cross_build
diff --git a/libc/docs/getting_started.rst b/libc/docs/getting_started.rst
new file mode 100644
index 00000000000000..a730b5e8ce7531
--- /dev/null
+++ b/libc/docs/getting_started.rst
@@ -0,0 +1,60 @@
+Getting Started
+===============
+
+Let's fetch the llvm-libc sources and build them.
+
+Install dependencies first:
+
+.. code-block:: sh
+
+  $ sudo apt update
+  $ sudo apt install git cmake ninja-build clang gcc-multilib wget unzip
+
+.. code-block:: sh
+
+  $ cd /tmp
+  $ wget https://github.com/llvm/llvm-project/archive/refs/heads/main.zip
+  $ unzip -q main.zip
+  $ mkdir llvm-project-main/build
+  $ cd llvm-project-main/build
+  $ cmake ../runtimes -GNinja \
+    -DLLVM_ENABLE_RUNTIMES="libc;compiler-rt" \
+    -DCMAKE_BUILD_TYPE=Debug \
+    -DCMAKE_CXX_COMPILER=clang++ \
+    -DCMAKE_C_COMPILER=clang \
+    -DLLVM_LIBC_FULL_BUILD=ON \
+    -DLLVM_LIBC_INCLUDE_SCUDO=ON \
+    -DCOMPILER_RT_BUILD_SCUDO_STANDALONE_WITH_LLVM_LIBC=ON \
+    -DCOMPILER_RT_BUILD_GWP_ASAN=OFF \
+    -DCOMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED=OFF
+  $ ninja libc libm
+
+This will produce the following artifacts:
+
+.. code-block::
+
+  llvm-project/build/libc/lib/libc.a
+  llvm-project/build/libc/lib/libm.a
+  llvm-project/build/libc/startup/linux/crt1.o
+  llvm-project/build/libc/include/**.h
+
+We can then compile and run hello world via:
+
+.. code-block:: c++
+
+  // hello.c
+  #include <stdio.h>
+  int main () { puts("hello world"); }
+
+.. code-block:: sh
+
+   $ clang -nostdinc -nostdlib hello.c -I libc/include \
+     -I $(clang -print-resource-dir)/include libc/startup/linux/crt1.o \
+     libc/lib/libc.a
+   $ ./a.out
+   hello world
+
+This was what we call a "full build" of llvm-libc. From here, you can visit
+:ref:`full_host_build` for more info, :ref:`full_cross_build` for cross
+compiling, :ref:`overlay_mode` for mixing llvm-libc with another libc, or
+:ref:`libc_gpu` for targeting GPUs.
diff --git a/libc/docs/index.rst b/libc/docs/index.rst
index 0cbf75f5e0ef2d..12dcba27a906bb 100644
--- a/libc/docs/index.rst
+++ b/libc/docs/index.rst
@@ -38,31 +38,31 @@ LLVM-libc aspires to a unique place in the software ecosystem.  The goals are:
 
 .. toctree::
    :hidden:
-   :maxdepth: 2
-   :caption: Using
+   :maxdepth: 1
+   :caption: Status & Support
 
-   usage_modes
-   overlay_mode
-   fullbuild_mode
-   configure
-   gpu/index.rst
+   headers/index.rst
+   arch_support
+   platform_support
+   compiler_support
 
 .. toctree::
    :hidden:
    :maxdepth: 1
-   :caption: Status
+   :caption: Simple Usage
 
-   headers/index.rst
-   c23
+   getting_started
 
 .. toctree::
    :hidden:
    :maxdepth: 1
-   :caption: Support
+   :caption: Advanced Usage
 
-   arch_support
-   platform_support
-   compiler_support
+   full_host_build
+   full_cross_build
+   overlay_mode
+   gpu/index.rst
+   configure
 
 .. toctree::
    :hidden:
@@ -73,13 +73,13 @@ LLVM-libc aspires to a unique place in the software ecosystem.  The goals are:
    dev/index.rst
    porting
    contributing
-   talks
 
 .. toctree::
    :hidden:
    :maxdepth: 1
-   :caption: External Links
+   :caption: Useful Links
 
+   talks
    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>
diff --git a/libc/docs/porting.rst b/libc/docs/porting.rst
index a4df4e8cf0719d..5747a8b9b0c73c 100644
--- a/libc/docs/porting.rst
+++ b/libc/docs/porting.rst
@@ -68,7 +68,7 @@ The entrypoints.txt file
 One of the important pieces of config information is listed in a file named
 ``entrypoints.txt``. This file lists the targets for the entrypoints (see
 :ref:`entrypoints`) you want to include in the static archive of the libc (for
-the :ref:`overlay_mode` and/or the :ref:`fullbuild_mode`.) If you are doing an
+the :ref:`overlay_mode` and/or the :ref:`full_host_build`.) If you are doing an
 architecture specific bring up, then an ``entrypoints.txt`` file should be
 created in the architecture subdirectory for each architecture. Else, having a
 single ``entrypoints.txt`` in the operating system directory is sufficient.
@@ -95,7 +95,7 @@ The headers.txt file
 Another important piece of config information is listed in a file named
 ``headers.txt``. It lists the targets for the set of public headers that are
 provided by the libc. This is relevant only if the libc is to be used in the
-:ref:`fullbuild_mode` on the target operating system and architecture. As with
+:ref:`full_host_build` on the target operating system and architecture. As with
 the ``entrypoints.txt`` file, one ``headers.txt`` file should be listed for
 each individual target architecture if you are doing an architecture specific
 bring up. The Linux config has ``headers.txt`` file listed separately for the
diff --git a/libc/docs/usage_modes.rst b/libc/docs/usage_modes.rst
deleted file mode 100644
index 8e5dcca6e0a75c..00000000000000
--- a/libc/docs/usage_modes.rst
+++ /dev/null
@@ -1,15 +0,0 @@
-===========
-Usage Modes
-===========
-
-The libc can used in two different modes:
-
-#. The **overlay** mode: In this mode, the link order semantics are exploited
-   to overlay implementations from LLVM's libc over the system libc. See
-   :ref:`overlay_mode` for more information about this mode. In this mode, libc
-   uses the ABI of the system it's being overlayed onto. Headers are NOT
-   generated. libllvmlibc.a is the only build artifact.
-#. The **fullbuild** mode: In this mode, LLVM's libc is used as the only libc
-   for the binary. See :ref:`fullbuild_mode` for information about this mode.
-   In this mode, libc uses its own ABI. Headers are generated along with a
-   libc.a.

[nickdesaulniers]

is an example of rendering the new TOC

[michaelrj-google]

LGTM