Cleanup

Author: thomas-bc

cmake/docs/docs.py

@@ -23,12 +23,13 @@
 
 LINE_RE = re.compile(r"^#{1,4} ?")
 
+# Directories to exclude from doc generation
 EXCLUDED = [
     "test",
     "googletest-download",
 ]
+# CURRENT_DIR tracks which directory docs are currently being generated for
 CURRENT_DIR = Path(".")
-CURRENT_OFFSET = 0
 
 
 class DocState(enum.IntEnum):
@@ -68,7 +69,7 @@ def main():
 
 def process_file(file_name, outdir):
     """Process a file"""
-    global CURRENT_DIR, CURRENT_OFFSET
+    global CURRENT_DIR
     if any([Path(x) in Path(file_name).parents for x in EXCLUDED]):
         return
     # Read a line, and output it
@@ -83,17 +84,17 @@ def process_file(file_name, outdir):
     relative_fn = out_fn
     out_fn = os.path.join(outdir, out_fn)
     os.makedirs(os.path.dirname(out_fn), exist_ok=True)
-    # Open both files, and loop over all the lines reading and writing each
+    # If parent is not current dir, change CURRENT_DIR and print section header
+    # This conveniently works because os.walk is depth first (used in main())
     if Path(file_name).parent != CURRENT_DIR:
         CURRENT_DIR = Path(file_name).parent
-        CURRENT_OFFSET = len(Path(file_name).relative_to(CURRENT_DIR).parents)
-        print(f"## {CURRENT_DIR}")
-    print("  " * CURRENT_OFFSET, end="")
+        print(f"### {CURRENT_DIR}")
     print(
         "- [{}](../api/cmake/{})".format(
-            os.path.basename(out_fn).replace(".md", ""), relative_fn
+            os.path.basename(out_fn).replace(".md", ""), relative_fn.lstrip("./")
         )
     )
+    # Open both files, and loop over all the lines reading and writing each
     with open(file_name, "r") as in_file_handle:
         with open(out_fn, "w") as out_file_handle:
             state = DocState.SEARCH

docs/UsersGuide/cmake/Targets.md

@@ -14,23 +14,9 @@ For projects generating GNU make files, these targets can be executed with the `
 ## Built-In Targets
 
 The CMake system supplies several targets that are useful for all projects and thus are included
-as part of the CMake system. These targets are described in more detail below.
+as part of the CMake system. These targets are described in the [index](cmake-api.md)
 
-### `<MODULE>_coverage` Targets
-
-The coverage target works on systems where the `gcov` executable is available on the executable
-search path and the `CMAKE_BUILD_TYPE` variable has been set to `TESTING`. If these two conditions
-are met, then the user can build both the `<MODULE>_coverage` targets to run unit tests and generate
-coverage reports for the specified module.
-
-See: [coverage.md](coverage.md)
-
-### `dict` Target
-
-The target system is also used to produce dictionaries. These dictionaries can be created using the
-top-level `dict` target. Dictionaries do not make use of module-specific targets in terms of user
-interaction.
 
 ## Adding Custom Targets
 
-See [support/Target.md](../support/Target.md) for a description of adding custom targets.
+See the [Customization Guide](Customization.md) for a description of adding custom targets.

docs/UsersGuide/cmake/cmake-api.md

@@ -1,12 +1,12 @@
 ## User API Documentation
 
-These links point to documentation needed by average users of the CMake system. The API link
+These links point to documentation needed by most users of the CMake system. The API link
 describes the module-level API for working with CMake. This is where users should look for the full
 descriptions of module-level functions. Options describe the runtime options that the CMake system
 takes. Users wanting to alter the build should look here.
 
-- [Options](../api/cmake/Options.md): Runtime build options
 - [API](../api/cmake/API.md): Module API function documentation
+- [Options](../api/cmake/Options.md): Runtime build options
 
 ## Toolchain and Platform Documentation
 
@@ -21,10 +21,10 @@ own toolchains for F´.
 Platform files are used to set up F´ for use on specific hardware platforms. This allows users to
 define types and headers needed for F´ for any embedded system they desire.
 
-[Platform Template](../api/cmake/platform/platform-template.md): Platform file template documentation
-[Linux](../api/cmake/platform/Linux.md): Linux platform support
-[Darwin](../api/cmake/platform/Darwin.md): Darwin (macOS) platform support
-[rtems5](../api/cmake/platform/rtems5.md): RTEMS 5 initial support
+[Platform Template](../api/cmake/platform/platform-template.md): Platform file template documentation  
+[Linux](../api/cmake/platform/Linux.md): Linux platform support  
+[Darwin](../api/cmake/platform/Darwin.md): Darwin (macOS) platform support  
+[rtems5](../api/cmake/platform/rtems5.md): RTEMS 5 initial support  
 
 ## Target Documentation
 
@@ -33,11 +33,7 @@ generically integrated to support both module-level and global targets building
 F´ "target".  For example, the "dict" target may build local dictionary fragments and then roll
 them into a global dictionary.
 
-[Target](../api/cmake/support/Target.md): target subsystem documentation
-[dict](../api/cmake/target/dict.md): `dict` target documentation
-[impl](../api/cmake/target/impl.md): `impl` target documentation
-[testimpl](../api/cmake/target/testimpl.md): `testimpl` target documentation
-[coverage](../api/cmake/target/coverage.md): `coverage` target documentation
+[Target](./Targets.md): target subsystem documentation
 
 
 ## CMake Support Code Documentation
@@ -46,9 +42,9 @@ These links describe the internal CMake function references. These should be con
 improvements to the CMake are needed. Build system architects should consult this section.
 
 
-[FPrime Code](../api/cmake/FPrime-Code.md): F´ framework code inclusions
+[FPrime-Code](../api/cmake/FPrime-Code.md): F´ framework code inclusions  
 [FPrime](../api/cmake/FPrime.md): F´ project support
 
 
-## CMake Documentation Table of Contents
+## CMake Documentation Index