Restructure user manual for holding design patterns (#3222)

* Doc restructure with design-patterns and build-system sections

* Restore advanced.md and uts.md

* Link in UTs

* Fix link

* Remove card layout from user manual landing page

* Add back the cards

.gitignore

@@ -1,5 +1,6 @@
 build/
-build*/
+build-fprime-*/
+build-artifacts/
 gtest/
 docs-cache/
 CMakePresets.json

Fw/Dp/docs/sdd.md

@@ -5,7 +5,7 @@
 This build module defines FPP ports and C++ classes that support
 the collection and storage of data products.
 For more information on data products and records, see the
-[data products documentation](../../../docs/user-manual/design/data-products.md).
+[data products documentation](../../../docs/user-manual/framework/data-products.md).
 
 ## 2. Configuration
 

Svc/ComQueue/docs/sdd.md

@@ -11,9 +11,9 @@ passing in a configuration table at initialization. Queued messages from the hig
 first and a round-robin algorithm is used to balance between ports of shared priority.
 
 `Svc::ComQueue` is designed to act alongside instances of the
-[communication adapter interface](../../../docs/user-manual/design/communication-adapter-interface.md) and
+[communication adapter interface](../../../docs/reference/communication-adapter-interface.md) and
 implements the communication queue
-[protocol](../../../docs/user-manual/design/communication-adapter-interface.md#communication-queue-protocol).
+[protocol](../../../docs/reference/communication-adapter-interface.md#communication-queue-protocol).
 
 ## 2. Assumptions
 
@@ -21,7 +21,7 @@ implements the communication queue
 2. Data is considered to be successfully sent when a `Fw::Success::SUCCESS` signal was received
 3. The com adapter is responsible for any retransmission of failed data
 4. The system includes downstream components implementing the
- [communications adapter](../../../docs/user-manual/design/communication-adapter-interface.md)
+ [communications adapter](../../../docs/reference/communication-adapter-interface.md)
 
 
 ## 3. Requirements

Svc/ComStub/docs/sdd.md

@@ -3,7 +3,7 @@
 ## 1. Introduction
 
 `Svc::ComStub` is an example  F´ component implementing the
-[communication adapter interface](../../../docs/user-manual/design/communication-adapter-interface.md) required
+[communication adapter interface](../../../docs/reference/communication-adapter-interface.md) required
 to work with F´ communication components. Projects and users may choose to replace this with a complete communication
 implementation (i.e. a component managing a specific radio) once ready. As long as any communication implementation
 implements the communication adapter interface it can drop in and work with the standard F´ uplink and downlink setup.
@@ -38,7 +38,7 @@ used alongside the other F´ communication components (`Svc::Framer`, `Svc::Defr
 
 
 `Svc::ComStub` implements the
-[communication adapter interface](../../../docs/user-manual/design/communication-adapter-interface.md) by
+[communication adapter interface](../../../docs/reference/communication-adapter-interface.md) by
 delegation to a `Drv::ByteStreamDriverModel` as a way to transmit data and receive data. Other communication
 adapter implementations may follow-suite.
 
@@ -72,7 +72,7 @@ be useful
 
 `Svc::ComStub` has only stores a boolean `m_reinitialize` indicating when it should send `Fw::Success::SUCCESS` in
 response to a driver reconnection event. This is to implement the  Communication Adapter Protocol of a
-[communication adapter interface](../../../docs/user-manual/design/communication-adapter-interface.md).
+[communication adapter interface](../../../docs/reference/communication-adapter-interface.md).
 
 ### 4.3. Port Handlers
 

Svc/Framer/docs/sdd.md

@@ -20,9 +20,9 @@ You can use the standard F Prime downlink protocol implementation.
 This implementation works with the F Prime ground data system (GDS).
 
 `Svc::Framer` is designed to act alongside instances of the
-[communication adapter interface](../../../docs/user-manual/design/communication-adapter-interface.md). In order
+[communication adapter interface](../../../docs/reference/communication-adapter-interface.md). In order
 to work well with communication adapters, `Svc::Framer` implements the framer status
-[protocol](../../../docs/user-manual/design/communication-adapter-interface.md#framer-status-protocol).
+[protocol](../../../docs/reference/communication-adapter-interface.md#framer-status-protocol).
 
 ## 2. Assumptions
 

Svc/GenericHub/docs/sdd.md

@@ -1,6 +1,6 @@
 # Svc::GenericHub Generic Hub Component
 
-The Generic Hub component is an implementation of the F´ [hub pattern](../../../docs/user-manual/framework/hub-pattern.md).
+The Generic Hub component is an implementation of the F´ [hub pattern](../../../docs/user-manual/design-patterns/hub-pattern.md).
 This pattern (and component) is used to bridge across an address space barrier between F´ deployments and route F´ port
 calls to the remote deployment. It also receives incoming port calls from the remote component. Essentially, it is a
 port multiplexer/demultiplexer that serializes the port calls to an `Fw::Buffer` object and outputs this data to an 

cmake/API.cmake

@@ -697,8 +697,8 @@ endfunction()
 # Next Topics:
 #  - Setting Options: [Options](options.md) are used to vary a CMake build.
 #  - Adding Modules: [Modules](module.md) register fprime Ports, Components, etc.
-#  - Creating Toolchains: [Toolchains](../../../user-manual/cmake/cmake-toolchains.md) setup standard CMake Cross-Compiling.
-#  - Adding Platforms: [Platforms](../../../user-manual/cmake/cmake-platforms.md) help fprime set Cross-Compiling specific items.
+#  - Creating Toolchains: [Toolchains](../../../user-manual/build-system/cmake-toolchains.md) setup standard CMake Cross-Compiling.
+#  - Adding Platforms: [Platforms](../../../user-manual/build-system/cmake-platforms.md) help fprime set Cross-Compiling specific items.
 #  - Adding Targets: [Targets](./target/target.md) for help defining custom build targets
-#  - Implementation Packages Design: [Implementation Packages](../../../user-manual/design/package-implementations.md)
+#  - Implementation Packages Design: [Implementation Packages](../../../user-manual/build-system/package-implementations.md)
 ####

docs/how-to/develop-subtopologies.md

@@ -309,7 +309,7 @@ Now go ahead and run and build your deployment, and you should see that you have
 As you may notice, the current implementation of subtopologies lacks in a few areas of simplicity and especially reusability. A couple of these issues are tabulated here:
 
 1. It may be the case that I would like to have multiple uses of a subtopology `st` within a main topology `main`. For example, `st` could define the topology for managing a single temperature sensor, but I would like to implement $n$ number of those sensors. At the moment, to do this one would need to duplicate the entire subtopology and make proper modifications to instances, the TopologyDefs file, and more.
-2. Let's maintain our example of `st` being the topology for managing a single temperature sensor. It may be the case that `st` only implements the software behavior, as is reasonable: the developer of the subtopology probably cannot write hardware interface drivers for every platform possible. So, the user would provide the proper driver to `st`, which is again reasonable. However, to accomplish this one would need to modify the contents of a subtopology, changing instance definitions and possibly the connection graphs as well. Such a task could become monstrous if, say `st` now implements the [hub pattern](../user-manual/framework/hub-pattern.md).
+2. Let's maintain our example of `st` being the topology for managing a single temperature sensor. It may be the case that `st` only implements the software behavior, as is reasonable: the developer of the subtopology probably cannot write hardware interface drivers for every platform possible. So, the user would provide the proper driver to `st`, which is again reasonable. However, to accomplish this one would need to modify the contents of a subtopology, changing instance definitions and possibly the connection graphs as well. Such a task could become monstrous if, say `st` now implements the [hub pattern](../user-manual/design-patterns/hub-pattern.md).
 
 Thus, an autocoder [tool](https://github.com/fprime-community/fprime-subtopology-tool) dubbed the "Subtopology AC Tool" has been developed to be able to provide features like instantiation, local components, and formal subtopology interfaces. The tool itself provides examples of the syntax required to use these features, as well as a design methodology and a worked example with diagrams using a similar context to the one [in this document](#example-scenario).
 

docs/mkdocs.yml

@@ -161,6 +161,7 @@ nav:
       - Overview:
         - 'Introduction to F´': docs/user-manual/overview/full-intro.md
         - 'The F´ Ground Data System': docs/user-manual/overview/gds-introduction.md
+        - 'F´ Software Architecture': docs/user-manual/overview/fprime-architecture.md
         - 'F´ Development Process': docs/user-manual/overview/development-practice.md
         - 'A Tour of the Source Tree': docs/user-manual/overview/source-tree.md
         - 'Projects and Deployments': docs/user-manual/overview/proj-dep.md
@@ -174,12 +175,10 @@ nav:
         - 'Constructing the F´ Topology': docs/user-manual/framework/building-topology.md
         - 'Asserts in F´': docs/user-manual/framework/assert.md
         - 'F´ On Baremetal and Multi-Core Systems': docs/user-manual/framework/baremetal-multicore.md
-        - 'Application, Manager, Driver Pattern': docs/user-manual/framework/app-man-drv.md
         - 'Ground Interface': docs/user-manual/framework/ground-interface.md
         - 'Dynamic Memory and Buffer Management': docs/user-manual/framework/dynamic-memory.md
-        - 'The Hub Pattern': docs/user-manual/framework/hub-pattern.md
-        - 'settings.ini: Build Settings Configuration': docs/user-manual/framework/settings.md
-        - 'The F´ CMake Build System': docs/user-manual/cmake/cmake-intro.md
+        - 'F´ Data Products': docs/user-manual/framework/data-products.md
+        - 'State Machines': docs/user-manual/framework/state-machines.md
       - 'FPP': 'https://nasa.github.io/fpp/fpp-users-guide.html'
       - GDS:
         - "The GDS CLI": docs/user-manual/gds/gds-cli.md
@@ -187,17 +186,23 @@ nav:
         - 'GDS Dashboard Reference': docs/user-manual/gds/gds-dashboard-reference.md
         - 'Integration Test API': docs/user-manual/gds/gds-test-api-guide.md
         - 'Sequencing in F´': docs/user-manual/gds/seqgen.md
+      - Build System:
+        - 'The F´ CMake Build System': docs/user-manual/build-system/cmake-intro.md
+        - 'settings.ini: Build Settings Configuration': docs/user-manual/build-system/settings.md
+        - 'CMake Platforms': docs/user-manual/build-system/cmake-platforms.md
+        - 'CMake Toolchains': docs/user-manual/build-system/cmake-toolchains.md
+        - 'CMake User API': docs/user-manual/build-system/cmake-api.md
+        - 'CMake Targets': docs/user-manual/build-system/cmake-targets.md
+        - 'CMake Customization': docs/user-manual/build-system/cmake-customization.md
+        - 'Advanced CMake usage': docs/user-manual/build-system/cmake-advanced.md
+        - 'CMake Unit Testing': docs/user-manual/build-system/cmake-uts.md
+        - 'Package Implementations': docs/user-manual/build-system/package-implementations.md
       - Security:
         - 'Software Bill of Materials': docs/user-manual/security/software-bill-of-materials.md
-      - Design:
-        - 'F´ Software Architecture': docs/user-manual/design/fprime-architecture.md
-        - 'Numerical Types Design': docs/user-manual/design/numerical-types.md
-        - 'Communication Adapter Interface': docs/user-manual/design/communication-adapter-interface.md
-        - 'Package Implementations': docs/user-manual/design/package-implementations.md
-        - 'FPP JSON Dictionary Specification': docs/user-manual/design/fpp-json-dict.md
-        - 'Rate Groups and Timeliness': docs/user-manual/design/rate-group.md
-        - 'F´ Data Products': docs/user-manual/design/data-products.md
-        - 'State Machines': docs/user-manual/design/state-machines.md
+      - Design Patterns:
+        - 'Application, Manager, Driver Pattern': docs/user-manual/design-patterns/app-man-drv.md
+        - 'Rate Groups and Timeliness': docs/user-manual/design-patterns/rate-group.md
+        - 'The Hub Pattern': docs/user-manual/design-patterns/hub-pattern.md
     - How To: 
       - docs/how-to/index.md
       - 'F´ Library Development': docs/how-to/develop-fprime-libraries.md
@@ -209,7 +214,9 @@ nav:
       - 'C++ Documentation': docs/reference/api/cpp/html/index.html
       - 'F´ Components SDDs': docs/reference/sdd.md
       - 'FPP Language Specification': https://nasa.github.io/fpp/fpp-spec.html
-      - 'CMake User API': docs/user-manual/cmake/cmake-api.md
+      - 'FPP JSON Dictionary Specification': docs/reference/fpp-json-dict.md
+      - 'Numerical Types Design': docs/reference/numerical-types.md
+      - 'Communication Adapter Interface': docs/reference/communication-adapter-interface.md
       - 'GDS Developers Guide': docs/reference/gds-cli-dev.md
   - Support: '../support'
   - Events: '../events'

docs/reference/communication-adapter-interface.md

@@ -6,7 +6,7 @@ to operate with the standard F´ uplink and downlink components.
 
 Implementors of this interface are referred to as *Communication Adapters*.
 
-![Communication Adapter Interface](../../img/com-adapter.png)
+![Communication Adapter Interface](../img/com-adapter.png)
 
 The communication adapter interface protocol is designed to work alongside the framer status protocol and the com queue
 protocol to ensure that data messages do not overload a communication interface. These protocols are discussed below.

docs/reference/index.md

@@ -40,7 +40,7 @@ Technical reference for the F Prime C++ API, CMake API, FPP language specificati
 
     This section of the documentation captures step by step how tos for various F´ development tasks.
 
-    [View CMake User API Documentation](../user-manual/cmake/cmake-api.md){ .md-button .md-button--primary }
+    [View CMake User API Documentation](../user-manual/build-system/cmake-api.md){ .md-button .md-button--primary }
 
 
 </div>

docs/user-manual/build-system/cmake-advanced.md

@@ -96,7 +96,7 @@ make
 
 Sometimes users need to crack open the CMake structure in order to do things like adding an external
 library/build system, adding custom make targets, building utilities, etc. These issues are described
-here: [Customization](Customization.md)
+here: [Customization](./cmake-customization.md)
 
 
-Further documentation can be found in the SDD: [SDD.md](https://github.com/nasa/fprime/blob/devel/cmake/docs/sdd.md)
+Further documentation can be found in the CMake SDD: [SDD.md](https://github.com/nasa/fprime/blob/devel/cmake/docs/sdd.md)

docs/user-manual/build-system/cmake-api.md

@@ -34,7 +34,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](./Targets.md): target subsystem documentation
+[CMake Customization](./cmake-customization.md): Custom Build-System Commands (Make Targets)
 
 ## CMake Support Code Documentation
 

docs/user-manual/build-system/cmake-customization.md

@@ -29,8 +29,8 @@ add targets that don't have both per-module and global steps.
 See:
   - [add_custom_target](https://cmake.org/cmake/help/latest/command/add_custom_target.html) to view
 information on CMake targets.
-  - [Target](Targets.md) for the format of the target file
   - [API](cmake-api.md) for the syntax of the register call
+  - [Targets](cmake-targets.md) for information on the built-in targets
   - [F´ standard targets](https://github.com/nasa/fprime/tree/devel/cmake/target) as an example of adding targets
 
 **Example (Raw Global Target):**

docs/user-manual/build-system/cmake-intro.md

@@ -71,9 +71,3 @@ 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
 
-## Advanced CMake Usage
-
-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/user-manual/build-system/cmake-targets.md

@@ -14,9 +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 the [index](cmake-api.md)
+as part of the CMake system. These targets are defined in [cmake/target](https://github.com/nasa/fprime/tree/devel/cmake/target).
 
 
 ## Adding Custom Targets
 
-See the [Customization Guide](Customization.md) for a description of adding custom targets.
+See the [Customization Guide](cmake-customization.md) for a description of adding custom targets.

docs/user-manual/build-system/cmake-uts.md

@@ -14,4 +14,4 @@ standard a testing framework. Python `subprocess` is used to run CMake for its s
 ```
 fprime> cd cmake/test
 pytest
-```
+```

docs/user-manual/design/fprime-architecture.md

@@ -1,3 +0,0 @@
-# F´ Software Architecture
-
-Slide decks regarding the F´ Software Architecture, as well as general Flight Software design and architecture concepts, can be found here: https://github.com/fprime-community/fprime-course-materials

docs/user-manual/framework/baremetal-multicore.md

@@ -36,7 +36,7 @@ of that delegated execution context comes next.
 Since the OS is not around to execute F´, the implementer of the F´ project must choose an execution context for F´ to
 run on. That is, ensuring that some call invokes all of the **Components** that compose the F´ system. Otherwise, some
 components will not run. Typically, this is handled by composing an F´ baremetal system into components that are all
-driven by [rate groups](../design/rate-group.md). Designing the system this way ensures that all execution is derived from
+driven by [rate groups](../design-patterns/rate-group.md). Designing the system this way ensures that all execution is derived from
 one source: the rate group driver and thus reducing the problem to supplying an execution context to the rate group
 driver at a set rate.  All calls needed will execute during a sweep through the rate groups and their derived rates.
 
@@ -76,7 +76,7 @@ components to designated cores.  In general, these systems behave just fine.
 When running F´ on multi-platform systems, users typically define a deployment for each platform in the system. These
 deployments are then linked over the platform's inter-communication architecture.  Should  users want F´ execution
 across these deployments to look like a single F´ deployment, users are advised to adopt the
-[hub pattern](hub-pattern.md) to invoke F´ port calls across multiple devices.
+[hub pattern](../design-patterns/hub-pattern.md) to invoke F´ port calls across multiple devices.
 
 ## Thread Virtualization
 

docs/user-manual/framework/configuring-fprime.md

@@ -30,7 +30,7 @@ All configurable files (top-level and component-specific) for F´ are available
 Projects can also take ownership of the `config` directory to provide their own `AcConstants.fpp`
 and configuration `*.hpp` files. To do so, copy the `config` directory into your project and use the
 `config_directory` options in the project's `settings.ini` file.
-See the [settings.ini guide](settings.md) for more details.
+See the [settings.ini guide](../build-system/settings.md) for more details.
 
 The `FpConfig.h` file is a C header allowing the user to define global settings.
 Where components allow specific configuration, a `<component>Cfg.hpp` is available to be modified as well.
@@ -77,7 +77,7 @@ e.g.
 Many architectures support different sizes of types. In addition, projects may wish to change the size of the various
 custom types specified in the framework. This section will describe these settings. These are typically provided by the
 and can be changed in the `FpConfig.h` header.  These types are described in the
-[numerical types design document](../design/numerical-types.md#configurable-integer-types).
+[numerical types design document](../../reference/numerical-types.md).
 
 The above document also describes the methods for configuring the configurable types used to adjust various fprime
 types.

docs/user-manual/index.md

@@ -5,22 +5,55 @@ hide:
 
 # User Manual
 
-The User Manual dives into F Prime design philosophy and architectural principles, providing a deep understanding of how the framework operates. Below are the different topics you can find under the User Manual. 
+The User Manual dives into F Prime concepts and usage, providing a deep understanding of how the framework operates. The different chapters are listed below.
 
-## __Overview__
-Technical overview of F Prime
 
-## __Framework__
-Dive into the mechanics and design philosophies of the F Prime framework
+<div class="grid cards boring" markdown>
 
-## __FPP (F Prime Prime)__
-In-depth user guide and language specification for FPP
+-   <span class="card-title">__Overview__</span>
 
-## __Ground Data System (GDS)__
-Dive into the F´ GDS and its testing framework
+    ---
 
-## __Security__
-Security documentation spanning the F Prime ecosystem
+    Technical overview of the F´ ecosystem.
 
-## __Design__
-Explanation of the F Prime architecture and design philosophies
+
+-   <span class="card-title">__Framework__</span>
+
+    ---
+
+    Learn concepts and mechanisms needed to build and use an F´ application.
+
+
+-   <span class="card-title">__FPP User's Guide__</span>
+
+    ---
+
+    In-depth user guide for F Prime Prime (FPP), the F´ modeling language.
+
+-   <span class="card-title">__F´ GDS__</span>
+
+    ---
+
+    Learn how to use the GDS and how it can be used to test F´ applications.
+
+-   <span class="card-title">__Build System__</span>
+
+    ---
+
+    Learn about the F´ build system and how to customize it.
+
+
+-   <span class="card-title">__Security__</span>
+
+    ---
+
+    Security considerations when designing and developing F´ applications.
+
+
+-   <span class="card-title">__Design Patterns__</span>
+
+    ---
+
+    Learn about common design patterns used in F´ applications.
+
+</div>

docs/user-manual/overview/cmd-evt-chn-prm.md

@@ -147,7 +147,7 @@ class function retrieves the time tag from the time source component and then wr
 database component. The telemetry database is called periodically to send the current set of telemetry to the ground.
 
 > [!NOTE]
-> the periodic call to the telemetry database is typically made by a [rate group](../design/rate-group.md).
+> the periodic call to the telemetry database is typically made by a [rate group](../design-patterns/rate-group.md).
 
 ## Parameters
 

docs/user-manual/overview/development-practice.md

@@ -71,7 +71,7 @@ After copying the Ref app, both in-tree and standalone deployments need to creat
 `settings.ini` file in the root of the deployment to set the deployment toolchain, library
 locations, and for standalone deployments, the location of the F´ framework.
 
-For details on configuring the `settings.ini` file, see the [user guide page](../framework/settings.md).
+For details on configuring the `settings.ini` file, see the [user guide page](../build-system/settings.md).
 
 
 ## Develop Ports and Components

docs/user-manual/overview/fprime-architecture.md

@@ -0,0 +1,6 @@
+# F´ Software Architecture Overview
+
+Slide decks regarding the F´ Software Architecture, as well as general Flight Software design and architecture concepts, can be found in [F Prime Course Materials](https://github.com/fprime-community/fprime-course-materials).  
+
+These materials are updated yearly and are used during our [Events](https://fprime.jpl.nasa.gov/events/).
+

docs/user-manual/overview/port-comp-top.md

@@ -103,7 +103,7 @@ input port type. This allows strongly-typed ports to connect to generic "pass-an
 in Figure 3. For input ports, the calling port detects a connection and serializes arguments. For the output ports,
 the serialized port calls an interface on the typed port that deserializes arguments. Serialization ports do not support
 ports with return types. These ports allow serialized data to be passed around by generic components that do not know
-the type contained. The [Hub pattern](../framework/hub-pattern.md) often uses serialized ports such that data can be routed
+the type contained. The [Hub pattern](../design-patterns/hub-pattern.md) often uses serialized ports such that data can be routed
 across an address-space gap in a generic fashion.
 
 ![Serialization Ports](../../img/core3.png)