From dd9efb33b9e014037d9e38cfc331ea2e38c9e30b Mon Sep 17 00:00:00 2001 From: Nick Desaulniers Date: Thu, 5 Dec 2024 13:54:09 -0800 Subject: [PATCH] [libc][docs] reorganize documentation (#118836) This commit does a few things: * creates libc/docs/headers/ and moves all user API related headers under it. * updates paths and docgen * updates the top level index to put these headers under a new "Implementation Status" tab. * rename some of the files to be foo.rst for foo.h (except strings, which is currently a mix of string.h and stdlib.h) * update the heading of some files to be in the form foo.h. --- libc/docs/{ => headers}/complex.rst | 2 +- libc/docs/{ => headers}/ctype.rst | 2 +- libc/docs/{ => headers}/fenv.rst | 2 +- libc/docs/headers/index.rst | 18 ++++++++++++++++++ libc/docs/{ => headers}/math/index.rst | 8 ++++---- libc/docs/{ => headers}/math/log.rst | 0 libc/docs/{ => headers}/math/stdfix.rst | 2 +- .../{libc_search.rst => headers/search.rst} | 8 ++++---- libc/docs/{ => headers}/setjmp.rst | 2 +- libc/docs/{ => headers}/signal.rst | 2 +- libc/docs/{ => headers}/stdbit.rst | 2 +- libc/docs/{ => headers}/stdio.rst | 8 ++++---- libc/docs/{ => headers}/strings.rst | 2 +- libc/docs/{ => headers}/threads.rst | 2 +- .../{date_and_time.rst => headers/time.rst} | 8 ++++---- libc/docs/index.rst | 13 +------------ libc/utils/docgen/docgen.py | 2 +- 17 files changed, 45 insertions(+), 38 deletions(-) rename libc/docs/{ => headers}/complex.rst (99%) rename libc/docs/{ => headers}/ctype.rst (97%) rename libc/docs/{ => headers}/fenv.rst (98%) create mode 100644 libc/docs/headers/index.rst rename libc/docs/{ => headers}/math/index.rst (99%) rename libc/docs/{ => headers}/math/log.rst (100%) rename libc/docs/{ => headers}/math/stdfix.rst (99%) rename libc/docs/{libc_search.rst => headers/search.rst} (95%) rename libc/docs/{ => headers}/setjmp.rst (95%) rename libc/docs/{ => headers}/signal.rst (99%) rename libc/docs/{ => headers}/stdbit.rst (99%) rename libc/docs/{ => headers}/stdio.rst (96%) rename libc/docs/{ => headers}/strings.rst (99%) rename libc/docs/{ => headers}/threads.rst (98%) rename libc/docs/{date_and_time.rst => headers/time.rst} (99%) diff --git a/libc/docs/complex.rst b/libc/docs/headers/complex.rst similarity index 99% rename from libc/docs/complex.rst rename to libc/docs/headers/complex.rst index 1e74f16b60e660b..2e81aba97b0ef67 100644 --- a/libc/docs/complex.rst +++ b/libc/docs/headers/complex.rst @@ -1,4 +1,4 @@ -.. include:: check.rst +.. include:: ../check.rst ========= complex.h diff --git a/libc/docs/ctype.rst b/libc/docs/headers/ctype.rst similarity index 97% rename from libc/docs/ctype.rst rename to libc/docs/headers/ctype.rst index 66e6f12b87818c3..e506830809f7956 100644 --- a/libc/docs/ctype.rst +++ b/libc/docs/headers/ctype.rst @@ -1,4 +1,4 @@ -.. include:: check.rst +.. include:: ../check.rst ======= ctype.h diff --git a/libc/docs/fenv.rst b/libc/docs/headers/fenv.rst similarity index 98% rename from libc/docs/fenv.rst rename to libc/docs/headers/fenv.rst index d910ba8852f68cb..374b46ef57be0a0 100644 --- a/libc/docs/fenv.rst +++ b/libc/docs/headers/fenv.rst @@ -1,4 +1,4 @@ -.. include:: check.rst +.. include:: ../check.rst ====== fenv.h diff --git a/libc/docs/headers/index.rst b/libc/docs/headers/index.rst new file mode 100644 index 000000000000000..2a7bf59e0b56dbe --- /dev/null +++ b/libc/docs/headers/index.rst @@ -0,0 +1,18 @@ +Implementation Status +===================== + +.. toctree:: + :maxdepth: 1 + + complex + ctype + fenv + math/index.rst + search + setjmp + signal + stdbit + stdio + strings + threads + time diff --git a/libc/docs/math/index.rst b/libc/docs/headers/math/index.rst similarity index 99% rename from libc/docs/math/index.rst rename to libc/docs/headers/math/index.rst index 4934e93ccb1645d..adc0afa080ec2a2 100644 --- a/libc/docs/math/index.rst +++ b/libc/docs/headers/math/index.rst @@ -1,10 +1,10 @@ .. _math: -============== -Math Functions -============== +====== +math.h +====== -.. include:: ../check.rst +.. include:: ../../check.rst .. raw:: html diff --git a/libc/docs/math/log.rst b/libc/docs/headers/math/log.rst similarity index 100% rename from libc/docs/math/log.rst rename to libc/docs/headers/math/log.rst diff --git a/libc/docs/math/stdfix.rst b/libc/docs/headers/math/stdfix.rst similarity index 99% rename from libc/docs/math/stdfix.rst rename to libc/docs/headers/math/stdfix.rst index d8dcb0cfa4c521d..58052f000995cd9 100644 --- a/libc/docs/math/stdfix.rst +++ b/libc/docs/headers/math/stdfix.rst @@ -2,7 +2,7 @@ StdFix Functions ================ -.. include:: ../check.rst +.. include:: ../../check.rst Standards and Goals ------------------- diff --git a/libc/docs/libc_search.rst b/libc/docs/headers/search.rst similarity index 95% rename from libc/docs/libc_search.rst rename to libc/docs/headers/search.rst index 774622d1e66c3f9..51832e9bdc2ed4b 100644 --- a/libc/docs/libc_search.rst +++ b/libc/docs/headers/search.rst @@ -1,8 +1,8 @@ -============= -Search Tables -============= +======== +search.h +======== -.. include:: check.rst +.. include:: ../check.rst --------------- Source Location diff --git a/libc/docs/setjmp.rst b/libc/docs/headers/setjmp.rst similarity index 95% rename from libc/docs/setjmp.rst rename to libc/docs/headers/setjmp.rst index 3739e73685b4bbf..b0091134f1a6b20 100644 --- a/libc/docs/setjmp.rst +++ b/libc/docs/headers/setjmp.rst @@ -1,4 +1,4 @@ -.. include:: check.rst +.. include:: ../check.rst ======== setjmp.h diff --git a/libc/docs/signal.rst b/libc/docs/headers/signal.rst similarity index 99% rename from libc/docs/signal.rst rename to libc/docs/headers/signal.rst index 172dd4a048ae9ac..b59ae0934235749 100644 --- a/libc/docs/signal.rst +++ b/libc/docs/headers/signal.rst @@ -1,4 +1,4 @@ -.. include:: check.rst +.. include:: ../check.rst ======== signal.h diff --git a/libc/docs/stdbit.rst b/libc/docs/headers/stdbit.rst similarity index 99% rename from libc/docs/stdbit.rst rename to libc/docs/headers/stdbit.rst index 3718ff8dc0df265..0484d951e19c6b4 100644 --- a/libc/docs/stdbit.rst +++ b/libc/docs/headers/stdbit.rst @@ -1,4 +1,4 @@ -.. include:: check.rst +.. include:: ../check.rst ======== stdbit.h diff --git a/libc/docs/stdio.rst b/libc/docs/headers/stdio.rst similarity index 96% rename from libc/docs/stdio.rst rename to libc/docs/headers/stdio.rst index d17821562c25567..3cd355529d40056 100644 --- a/libc/docs/stdio.rst +++ b/libc/docs/headers/stdio.rst @@ -1,8 +1,8 @@ -=============== -StdIO Functions -=============== +======= +stdio.h +======= -.. include:: check.rst +.. include:: ../check.rst --------------- Source location diff --git a/libc/docs/strings.rst b/libc/docs/headers/strings.rst similarity index 99% rename from libc/docs/strings.rst rename to libc/docs/headers/strings.rst index 427644c407ae839..949c53bfa4f740d 100644 --- a/libc/docs/strings.rst +++ b/libc/docs/headers/strings.rst @@ -2,7 +2,7 @@ String Functions ================ -.. include:: check.rst +.. include:: ../check.rst --------------- Source location diff --git a/libc/docs/threads.rst b/libc/docs/headers/threads.rst similarity index 98% rename from libc/docs/threads.rst rename to libc/docs/headers/threads.rst index db2d6630a238c07..39ee049eb1f8f5e 100644 --- a/libc/docs/threads.rst +++ b/libc/docs/headers/threads.rst @@ -1,4 +1,4 @@ -.. include:: check.rst +.. include:: ../check.rst ========= threads.h diff --git a/libc/docs/date_and_time.rst b/libc/docs/headers/time.rst similarity index 99% rename from libc/docs/date_and_time.rst rename to libc/docs/headers/time.rst index b745a3b416f802c..de82d80a2bec486 100644 --- a/libc/docs/date_and_time.rst +++ b/libc/docs/headers/time.rst @@ -1,8 +1,8 @@ -======================= -Date and Time Functions -======================= +====== +time.h +====== -.. include:: check.rst +.. include:: ../check.rst --------------- Source location diff --git a/libc/docs/index.rst b/libc/docs/index.rst index 6f759aa215b62cc..01f36709dfa5495 100644 --- a/libc/docs/index.rst +++ b/libc/docs/index.rst @@ -64,19 +64,8 @@ stages there is no ABI stability in any form. :caption: Status compiler_support - date_and_time - math/index.rst - strings - stdio - stdbit - fenv - libc_search + headers/index.rst c23 - ctype - complex - signal - threads - setjmp .. toctree:: :hidden: diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py index 016a3dae9aaa0f4..aa30a6e51ef8706 100755 --- a/libc/utils/docgen/docgen.py +++ b/libc/utils/docgen/docgen.py @@ -161,7 +161,7 @@ def print_macros_rst(header: Header, macros: Dict): def print_impl_status_rst(header: Header, api: Dict): - print(".. include:: check.rst\n") + print(".. include:: ../check.rst\n") print("=" * len(header.name)) print(header.name)