Improve linkage of CMake documentation (#2355)

.gitignore

@@ -44,6 +44,7 @@ coverity.out
 .#*
 
 **/docs/*.html
+/docs/UsersGuide/api/cmake/*
 *-template
 
 logs
@@ -53,9 +54,6 @@ core
 
 *.swp4
 
-./Gds/logs/*
-./Gds/docs/doxy
-
 *AppDictionary.xml
 *TopologyAppID.csv
 *TopologyAppAi_IDTableLog.txt
@@ -71,9 +69,6 @@ build-fprime-automatic*
 /ci-logs*
 TesterBase.*
 GTestBase.*
-/Fw/Python/.eggs
-/Fw/Python/src/fprime.egg-info
-/Gds/src/fprime_gds.egg-info
 **/DefaultDict/serializable/*
 
 fprime-venv

cmake/docs/docs.py

@@ -69,11 +69,9 @@ def process_file(file_name, outdir):
     )
     if out_fn == file_name:
         raise AssertionError("File collision imminent")
-    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
-    print("[{}]({})".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

cmake/platform/Linux.cmake

@@ -1,7 +1,7 @@
 ####
 # Linux.cmake:
 #
-# Linux platform file for standard linux targets. Merely defers to [./Linux-common.cmake](Linux-common.cmake).
+# Linux platform file for standard linux targets.
 ####
 # Set platform default for baremetal scheduler drivers
 if (NOT DEFINED FPRIME_USE_BAREMETAL_SCHEDULER)

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,14 @@
 ## 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
+
+An index of all available documentation is available at [CMake API Index](../api/cmake/index.md). This documentation is generated from the source code available [here](https://github.com/nasa/fprime/tree/devel/cmake). Below is a description of some of the main API functionalities.
 
 ## Toolchain and Platform Documentation
 
@@ -14,18 +16,17 @@ 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.
 
-[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
-[CMakeLists.txt](./platform/CMakeLists.txt.md)
+[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
 
@@ -34,11 +35,9 @@ 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
+
+All available targets are listed and described in the [CMake API Index](../api/cmake/index.md)
 
 
 ## CMake Support Code Documentation
@@ -47,11 +46,5 @@ 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
-[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

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

@@ -74,17 +74,18 @@ This section is divided into three sub-sections:
     - [Asserts in F´](./dev/assert.md)
     - [GDS Dashboard Reference](./dev/gds-dashboard-reference.md)
     - [Integration Test API](./dev/testAPI/user_guide.md)
-    - [v3 Migration Guide](./user/v3-migration-guide.md)
+    - [CMake User Guide](./cmake/cmake-intro.md)
 - Advanced F´ Topics:
     - [F´ Python Guidelines](./dev/py-dev.md)
     - [Porting F´ To a New Platform](./dev/porting-guide.md)
     - [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)
+    - [v3 Migration Guide](./user/v3-migration-guide.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/_includes/toc.md

@@ -69,7 +69,7 @@
         <li><a href="/fprime/UsersGuide/dev/assert.html">Asserts in F´</a></li>
         <li><a href="/fprime/UsersGuide/dev/gds-dashboard-reference.html">GDS Dashboard Reference</a></li>
         <li><a href="/fprime/UsersGuide/dev/testAPI/user_guide.html">Integration Test API</a></li>
-        <li><a href="/fprime/UsersGuide/user/v3-migration-guide.html">v3 Migration Guide</a></li>
+        <li><a href="/fprime/UsersGuide/cmake/cmake-intro.html">CMake User Guide</a></li>
       </ul>
     </details>
     <details>
@@ -80,6 +80,7 @@
         <li><a href="/fprime/UsersGuide/dev/baremetal-multicore.html">F´ On Baremetal and Multi-Core Systems</a></li>
         <li><a href="/fprime/UsersGuide/dev/configure-ide.html">Configuring an IDE for Use With F´</a></li>
         <li><a href="/fprime/UsersGuide/dev/os-docs.html">OS Layer Description</a></li>
+        <li><a href="/fprime/UsersGuide/user/v3-migration-guide.html">v3 Migration Guide</a></li>
       </ul>
     </details>
     <details>
@@ -87,7 +88,7 @@
       <ul>
         <li><a href="/fprime/UsersGuide/dev/gds-cli-dev.html">GDS CLI Design</a></li>
         <li><a href="/fprime/UsersGuide/api/c++/html/index.html">C++ Documentation</a></li>
-        <li><a href="/fprime/UsersGuide/api/cmake/API.html">CMake User API</a></li>
+        <li><a href="/fprime/UsersGuide/cmake/cmake-api.html">CMake User API</a></li>
       </ul>
     </details>
   </ul>

docs/doxygen/generate_docs.bash

@@ -9,7 +9,6 @@ APIDOCS="${FPRIME}/docs/UsersGuide/api"
 
 DOXY_OUTPUT="${FPRIME}/docs/UsersGuide/api/c++"
 CMAKE_OUTPUT="${FPRIME}/docs/UsersGuide/api/cmake"
-PY_OUTPUT="${FPRIME}/docs/UsersGuide/api/python"
 
 VERSIONED_OUTPUT="${1:-}"
 
@@ -89,7 +88,14 @@ 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/" "${CMAKE_OUTPUT}"
+    "${FPRIME}/docs/doxygen/index_gen.py" "${CMAKE_OUTPUT}" 'CMake API Index' 'test,googletest-download' > "${CMAKE_OUTPUT}/index.md"
+) || exit 1
+
+# Generate full index
+(
+    cd "${FPRIME}"
+    "${FPRIME}/docs/doxygen/index_gen.py" "${FPRIME}/docs" "F´ Documentation Index" "_data,_includes,doxygen,img" > "${FPRIME}/docs/doc-index.md"
 ) || exit 1
 
 # Fix for github pages

docs/doxygen/index_gen.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""
+index_gen.py:
+
+Generates a markdown index for all the `.md` files in a directory (recursively). This prints out
+to stdout by default, therefore redirects are needed to write out to a file.
+
+Usage:
+    index_gen.py <directory> <title> <excludes>
+
+    directory: The directory to generate the index for
+    title: The title to use for the header of the generated markdown
+    excludes: A list of directories to exclude from the index (comma-separated)
+
+@author thomas-bc
+"""
+
+import os
+import sys
+from pathlib import Path
+import argparse
+
+
+parser = argparse.ArgumentParser(
+    description="Generates a markdown index for all the `.md` files in a directory (recursively)."
+)
+parser.add_argument(
+    "directory", type=str, help="The directory to generate the index for"
+)
+parser.add_argument(
+    "title", type=str, help="The title to use for the header of the generated file"
+)
+parser.add_argument(
+    "excludes", type=str, help="Comma-separated list of directories to exclude"
+)
+args = parser.parse_args()
+
+
+def main():
+    if not Path(args.directory).exists():
+        print(f"[ERROR] {args.directory} is not a directory!")
+        sys.exit(2)
+    # Print the index header (stdout is redirected to index.md)
+    print(f"# {args.title}")
+    os.chdir(args.directory)
+    for path in sorted_listdir(Path(".")):
+        if path.name not in args.excludes.split(","):
+            process_path(path)
+
+
+def process_path(path: Path):
+    """Process a path recursively, printing out the index"""
+    depth = len(path.relative_to(Path(".")).parts)
+    if path.is_dir():
+        if any([path.name.endswith(".md") for path in sorted_listdir(path)]):
+            print(f"#{'#' * depth} {path}")
+        for subpath in sorted_listdir(path):
+            process_path(subpath)
+    elif path.is_file() and path.suffix == ".md":
+        print(f"- [{path.stem}]({path.relative_to(Path('.'))})")
+
+
+def sorted_listdir(path: Path):
+    """
+    Return a sorted list of paths in a directory. List is sorted by files first, then
+    directories. Files first is required to ensure the index is correctly generated
+    """
+    return sorted([path for path in path.iterdir() if path.is_file()]) + sorted(
+        [path for path in path.iterdir() if path.is_dir()]
+    )
+
+
+if __name__ == "__main__":
+    main()