[libc][docs] Introduce docgen

libc/docs/fenv.rst

@@ -0,0 +1,64 @@
+.. include:: check.rst
+
+fenv.h Functions
+================
+
+.. list-table::
+  :widths: auto
+  :align: center
+  :header-rows: 1
+
+  * - Function
+    - Implemented
+    - Standard
+  * - fe_dec_getround
+    -
+    - 7.6.5.3
+  * - fe_dec_setround
+    -
+    - 7.6.5.6
+  * - feclearexcept
+    - |check|
+    - 7.6.4.1
+  * - fegetenv
+    - |check|
+    - 7.6.6.1
+  * - fegetexceptflag
+    - |check|
+    - 7.6.4.2
+  * - fegetmode
+    -
+    - 7.6.5.1
+  * - fegetround
+    - |check|
+    - 7.6.5.2
+  * - feholdexcept
+    - |check|
+    - 7.6.6.2
+  * - feraiseexcept
+    - |check|
+    - 7.6.4.3
+  * - fesetenv
+    - |check|
+    - 7.6.6.3
+  * - fesetexcept
+    -
+    - 7.6.4.4
+  * - fesetexceptflag
+    - |check|
+    - 7.6.4.5
+  * - fesetmode
+    -
+    - 7.6.5.4
+  * - fesetround
+    - |check|
+    - 7.6.5.5
+  * - fetestexcept
+    - |check|
+    - 7.6.4.7
+  * - fetestexceptflag
+    -
+    - 7.6.4.6
+  * - feupdateenv
+    - |check|
+    - 7.6.6.4

libc/docs/index.rst

@@ -66,6 +66,7 @@ stages there is no ABI stability in any form.
    strings
    stdio
    stdbit
+   fenv
    libc_search
    c23
 

libc/utils/docgen/ctype.json

@@ -0,0 +1,7 @@
+{
+  "functions": {
+    "isalnum": null,
+    "isalpha": null,
+    "isblank": null
+  }
+}

libc/utils/docgen/docgen.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python
+#
+# ====- Generate documentation for libc functions  ------------*- python -*--==#
+#
+# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+#
+# ==-------------------------------------------------------------------------==#
+from argparse import ArgumentParser, Namespace
+from pathlib import Path
+from typing import Dict
+import sys
+import json
+
+
+def load_api(hname: str) -> Dict:
+    p = Path(__file__).parent / Path(hname).with_suffix(".json")
+    api = p.read_text(encoding="utf-8")
+    return json.loads(api)
+
+
+# TODO: we may need to get more sophisticated for less generic implementations.
+# Does libc/src/{hname minus .h suffix}/{fname}.cpp exist?
+def is_implemented(hname: str, fname: str) -> bool:
+    return Path(
+        Path(__file__).parent.parent.parent,
+        "src",
+        hname.rstrip(".h"),
+        fname + ".cpp",
+    ).exists()
+
+
+def print_functions(header: str, functions: Dict):
+    for key in sorted(functions.keys()):
+        print(f"  * - {key}")
+
+        if is_implemented(header, key):
+            print("    - |check|")
+        else:
+            print("    -")
+
+        # defined is optional. Having any content is optional.
+        if functions[key] is not None and "defined" in functions[key]:
+            print(f'    - {functions[key]["defined"]}')
+        else:
+            print("    -")
+
+
+def print_header(header: str, api: Dict):
+    fns = f"{header} Functions"
+    print(fns)
+    print("=" * (len(fns)))
+    print(
+        f"""
+.. list-table::
+  :widths: auto
+  :align: center
+  :header-rows: 1
+
+  * - Function
+    - Implemented
+    - Standard"""
+    )
+    # TODO: how do we want to signal implementation of macros?
+    print_functions(header, api["functions"])
+
+
+def parse_args() -> Namespace:
+    parser = ArgumentParser()
+    choices = [p.with_suffix(".h").name for p in Path(__file__).parent.glob("*.json")]
+    parser.add_argument("header_name", choices=choices)
+    return parser.parse_args()
+
+
+if __name__ == "__main__":
+    args = parse_args()
+    api = load_api(args.header_name)
+
+    print_header(args.header_name, api)

libc/utils/docgen/fenv.json

@@ -0,0 +1,58 @@
+{
+  "macros": [
+    "__STDC_VERSION_FENV_H__"
+  ],
+  "functions": {
+    "feclearexcept": {
+      "defined": "7.6.4.1"
+    },
+    "fegetexceptflag": {
+      "defined": "7.6.4.2"
+    },
+    "feraiseexcept": {
+      "defined": "7.6.4.3"
+    },
+    "fesetexcept": {
+      "defined": "7.6.4.4"
+    },
+    "fesetexceptflag": {
+      "defined": "7.6.4.5"
+    },
+    "fetestexceptflag": {
+      "defined": "7.6.4.6"
+    },
+    "fetestexcept": {
+      "defined": "7.6.4.7"
+    },
+    "fegetmode": {
+      "defined": "7.6.5.1"
+    },
+    "fegetround": {
+      "defined": "7.6.5.2"
+    },
+    "fe_dec_getround": {
+      "defined": "7.6.5.3"
+    },
+    "fesetmode": {
+      "defined": "7.6.5.4"
+    },
+    "fesetround": {
+      "defined": "7.6.5.5"
+    },
+    "fe_dec_setround": {
+      "defined": "7.6.5.6"
+    },
+    "fegetenv": {
+      "defined": "7.6.6.1"
+    },
+    "feholdexcept": {
+      "defined": "7.6.6.2"
+    },
+    "fesetenv": {
+      "defined": "7.6.6.3"
+    },
+    "feupdateenv": {
+      "defined": "7.6.6.4"
+    }
+  }
+}