diff --git a/.gitignore b/.gitignore index 1e422e991c..bf3253455e 100644 --- a/.gitignore +++ b/.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 diff --git a/cmake/docs/docs.py b/cmake/docs/docs.py index 4ddb561c0c..7d75e894d4 100755 --- a/cmake/docs/docs.py +++ b/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 diff --git a/cmake/platform/Linux.cmake b/cmake/platform/Linux.cmake index 89beac4d55..aef6fea3e4 100644 --- a/cmake/platform/Linux.cmake +++ b/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) diff --git a/docs/UsersGuide/cmake/Targets.md b/docs/UsersGuide/cmake/Targets.md index cf340fedb5..de8de249c1 100644 --- a/docs/UsersGuide/cmake/Targets.md +++ b/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) -### `_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 `_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. \ No newline at end of file +See the [Customization Guide](Customization.md) for a description of adding custom targets. diff --git a/docs/UsersGuide/cmake/cmake-api.md b/docs/UsersGuide/cmake/cmake-api.md index 04bbbae1d4..e4131ef917 100644 --- a/docs/UsersGuide/cmake/cmake-api.md +++ b/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 \ No newline at end of file diff --git a/docs/UsersGuide/cmake/cmake-intro.md b/docs/UsersGuide/cmake/cmake-intro.md index 8ce0f81c74..9df9fe772e 100644 --- a/docs/UsersGuide/cmake/cmake-intro.md +++ b/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). \ No newline at end of file diff --git a/docs/UsersGuide/guide.md b/docs/UsersGuide/guide.md index 409ac152f8..d5e811779c 100644 --- a/docs/UsersGuide/guide.md +++ b/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) diff --git a/docs/_includes/toc.md b/docs/_includes/toc.md index 0d11fc80b5..4f2f9a8b62 100644 --- a/docs/_includes/toc.md +++ b/docs/_includes/toc.md @@ -69,7 +69,7 @@
  • Asserts in F´
  • GDS Dashboard Reference
  • Integration Test API
    • -
  • v3 Migration Guide
    • +
  • CMake User Guide
    • @@ -80,6 +80,7 @@
  • F´ On Baremetal and Multi-Core Systems
  • Configuring an IDE for Use With F´
  • OS Layer Description
    • +
  • v3 Migration Guide
    • @@ -87,7 +88,7 @@
    diff --git a/docs/doxygen/generate_docs.bash b/docs/doxygen/generate_docs.bash index 8252fe690d..10c9dfc44c 100755 --- a/docs/doxygen/generate_docs.bash +++ b/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 diff --git a/docs/doxygen/index_gen.py b/docs/doxygen/index_gen.py new file mode 100755 index 0000000000..a86d232eab --- /dev/null +++ b/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 <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()