Improve linkage of CMake documentation

cmake/docs/docs.py

@@ -19,9 +19,17 @@
 import os
 import re
 import sys
+from pathlib import Path
 
 LINE_RE = re.compile(r"^#{1,4} ?")
 
+EXCLUDED = [
+    "test",
+    "googletest-download",
+]
+CURRENT_DIR = Path(".")
+CURRENT_OFFSET = 0
+
 
 class DocState(enum.IntEnum):
     """
@@ -60,6 +68,9 @@ def main():
 
 def process_file(file_name, outdir):
     """Process a file"""
+    global CURRENT_DIR, CURRENT_OFFSET
+    if any([Path(x) in Path(file_name).parents for x in EXCLUDED]):
+        return
     # Read a line, and output it
     out_fn = file_name
     if os.path.basename(out_fn) == "CMakeLists.txt":
@@ -73,7 +84,16 @@ def process_file(file_name, outdir):
     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
-    print("[{}]({})".format(os.path.basename(out_fn).replace(".md", ""), relative_fn))
+    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(
+        "- [{}](../api/cmake/{})".format(
+            os.path.basename(out_fn).replace(".md", ""), relative_fn
+        )
+    )
     with open(file_name, "r") as in_file_handle:
         with open(out_fn, "w") as out_file_handle:
             state = DocState.SEARCH

docs/UsersGuide/cmake/cmake-api.md

@@ -14,9 +14,9 @@ Toolchain files are used to cross-compile F´. In general, standard CMake toolch
 to cross-compile, however; F´ includes several built-in toolchains and a template for writing your
 own toolchains for F´.
 
-[Toolchain Documentation](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html): CMake's toolchain documentation
-[Toolchain Template](./toolchain/toolchain-template.md): Toolchain file template documentation
-[raspberrypi](./toolchain/raspberrypi.md): Raspberry PI cross-compile toolchain file
+[CMake Toolchain Documentation](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html): CMake's toolchain documentation
+[Toolchain Template](../api/cmake/toolchain/toolchain-template.md): Toolchain file template documentation
+[raspberrypi](../api/cmake/toolchain/raspberrypi.md): Raspberry PI cross-compile toolchain file
 
 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.
@@ -25,7 +25,6 @@ define types and headers needed for F´ for any embedded system they desire.
 [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
-[CMakeLists.txt](./platform/CMakeLists.txt.md)
 
 ## Target Documentation
 
@@ -49,9 +48,7 @@ improvements to the CMake are needed. Build system architects should consult thi
 
 [FPrime Code](../api/cmake/FPrime-Code.md): F´ framework code inclusions
 [FPrime](../api/cmake/FPrime.md): F´ project support
-[Module](../api/cmake/support/Module.md): Module registry and autocode support
-[Executable](../api/cmake/support/Executable.md): Executable registry and autocoding support
-[Unit Test](../api/cmake/support/Unit_Test.md): Unit test registry and autocode support
-[Utils](../api/cmake/support/Utils.md): General utility functions
-[AC_Utils](../api/cmake/support/AC_Utils.md): Autocode utility implementation specific to the Python autocoder
-[Validation](../api/cmake/support/validation/Validation.md): Experimental validation support
+
+
+## CMake Documentation Table of Contents
+

docs/UsersGuide/cmake/cmake-intro.md

@@ -69,6 +69,11 @@ to the deployment `CMakeLists.txt`.
 The CMake automatically documented API describes the above steps with all details.  The index for this documentation can
 be found here: [CMake API](./cmake-api.md).
 
+## Build Options
+
+Options describe the runtime options that the CMake system takes. Users wanting to alter the build should look here.
+The list of all available options can be found here: [CMake Options](../api/cmake/options.md)
+
 ## Toolchains and Platforms
 
 To integrate with new hardware platforms users need to build or acquire a CMake toolchain file, and add a platform
@@ -77,9 +82,9 @@ support file to the F´ CMake system. These steps can be reviewed here:
 [CMake Toolchains](./cmake-toolchains.md): F´ CMake toolchain file usage
 [F´ Platforms](./cmake-platforms.md): F´ CMake platform files
 
-## Advance CMake Usage
+## Advanced CMake Usage
 
-Most users don't need the CMAke advanced usage, as they use `fprime-util`.  However, to use CMake without `fprime-util`
+Most users don't need the CMake advanced usage, as they use `fprime-util`.  However, to use CMake without `fprime-util`
 please see: [CMake Advanced Usage](./cmake-advanced.md)
 
 Should a user want to run the unit tests that check CMake, see [CMake UTs](./cmake-uts.md).

docs/UsersGuide/guide.md

@@ -81,10 +81,11 @@ This section is divided into three sub-sections:
     - [F´ On Baremetal and Multi-Core Systems](./dev/baremetal-multicore.md)
     - [Configuring an IDE for Use With F´](./dev/configure-ide.md)
     - [OS Layer Description](./dev/os-docs.md)
+    - [CMake User Guide](./cmake/cmake-intro.md)
 - API Documentation
     - [GDS CLI Design](./dev/gds-cli-dev.md)
     - [C++ Documentation](./api/c++/html/index.html)
-    - [CMake User API](./api/cmake/API.html)
+    - [CMake User API](./cmake/cmake-api.md)
 
 
 

docs/doxygen/generate_docs.bash

@@ -89,7 +89,7 @@ function make_version
     cd "${FPRIME}"
     clobber "${CMAKE_OUTPUT}"
     mkdir -p "${CMAKE_OUTPUT}"
-    "${FPRIME}/cmake/docs/docs.py" "${FPRIME}/cmake/" "${FPRIME}/docs/UsersGuide/api/cmake"
+    "${FPRIME}/cmake/docs/docs.py" "${FPRIME}/cmake/" "${FPRIME}/docs/UsersGuide/api/cmake" >> "${FPRIME}/docs/UsersGuide/cmake/cmake-api.md"
 ) || exit 1
 
 # Fix for github pages