Prototype initial Doxygen and Sphinx support

.github/workflows/docs.yml

@@ -0,0 +1,87 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake make git libxml2 libxml2-dev perl doxygen
+
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Configure environment
+        run: |
+          echo "MAKEFLAGS=-j$(nproc)" >> "$GITHUB_ENV"
+          echo "CML_HOME=$GITHUB_WORKSPACE" >> "$GITHUB_ENV"
+          echo "TRICK_HOME=$GITHUB_WORKSPACE/externals/trick" >> "$GITHUB_ENV"
+          echo "JEOD_HOME=$GITHUB_WORKSPACE/externals/jeod" >> "$GITHUB_ENV"
+          echo "SSL_CERT_FILE=/etc/pki/tls/cert.pem" >> "$GITHUB_ENV"
+
+      - name: Set up Python virtual environment
+        run: |
+          python3 -m venv .venv
+          source .venv/bin/activate
+          pip3 install --upgrade pip
+          pip3 install .
+
+      - name: Clone Trick
+        uses: ./.github/actions/build-trick
+        with:
+          trick-home: ${{ env.TRICK_HOME }}
+          clone-only: "true"
+
+      - name: Clone JEOD
+        uses: ./.github/actions/build-jeod
+        with:
+          trick-home: ${{ env.TRICK_HOME }}
+          jeod-home: ${{ env.JEOD_HOME }}
+          clone-only: "true"
+
+      - name: Build documentation
+        run: |
+          source .venv/bin/activate
+          cmake --workflow --preset documentation
+
+      - name: Upload pages preview
+        uses: actions/upload-artifact@v4
+        with:
+          name: html-docs
+          path: build/docs/sphinx
+          retention-days: 2
+
+      - name: Upload Pages artifact
+        if: github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build/docs/sphinx
+
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

CMakeLists.txt

@@ -104,6 +104,7 @@ set_target_properties(cml_shared PROPERTIES OUTPUT_NAME cml)
 # Iterate over each CML component (i.e., model directory). Include the associated
 # CMake file and add the sub-library as a target object for the main libcml.
 set(CML_HEADER_FILES)
+set(CML_SOURCE_FILES)
 set(CML_COMPONENTS
     dynamics
     environment
@@ -117,8 +118,23 @@ foreach (component ${CML_COMPONENTS})
     add_subdirectory(models/${component})
     target_sources(cml_static PRIVATE $<TARGET_OBJECTS:cml::${component}>)
     target_sources(cml_shared PRIVATE $<TARGET_OBJECTS:cml::${component}>)
+
+    # Save a list of all CML header files for use in other places. Headers are
+    # already stored as absolute paths.
     get_target_property(_COMPONENT_HEADERS cml::${component} HEADER_SET)
     list(APPEND CML_HEADER_FILES ${_COMPONENT_HEADERS})
+
+    # Save a list of all CML source files for use in other places. Note that source
+    # files are stored relative to their subdirectory, so we need to do a bit more
+    # work to convert these to absolute paths.
+    get_target_property(_COMPONENT_SRCDIR cml::${component} SOURCE_DIR)
+    get_target_property(_COMPONENT_SOURCES cml::${component} SOURCES)
+    foreach (_src ${_COMPONENT_SOURCES})
+        if (NOT IS_ABSOLUTE "${_src}")
+            set(_src "${_COMPONENT_SRCDIR}/${_src}")
+        endif()
+        list(APPEND CML_SOURCE_FILES "${_src}")
+    endforeach()
 endforeach()
 
 # Set library dependencies for libcml. This is mostly for unit test executables
@@ -160,6 +176,11 @@ endif()
 # ---------------------------------------------------------------------------- #
 add_subdirectory(trickified)
 
+# ---------------------------------------------------------------------------- #
+# Build documentation                                                          #
+# ---------------------------------------------------------------------------- #
+add_subdirectory(docs)
+
 # ---------------------------------------------------------------------------- #
 # Set up installation targets                                                  #
 # ---------------------------------------------------------------------------- #

CMakePresets.json

@@ -88,6 +88,12 @@
             "configurePreset": "user-release",
             "targets": ["trickify", "install"]
         },
+        {
+            "name": "documentation",
+            "description": "Only build documentation",
+            "configurePreset": "user-release",
+            "targets": ["documentation"]
+        },
         {
             "name": "dev",
             "description": "CML developer build. If you're not directly working on CML, this isn't for you.",
@@ -142,10 +148,25 @@
                 }
             ]
         },
+        {
+            "name": "documentation",
+            "description": "Build the CML documentation",
+            "displayName": "Build the CML documentation and nothing else",
+            "steps": [
+                {
+                    "type": "configure",
+                    "name": "user-release"
+                },
+                {
+                    "type": "build",
+                    "name": "documentation"
+                }
+            ]
+        },
         {
             "name": "dev",
             "description": "CML developer build",
-            "displayName": "Build CML and all other extra targets, like tests and documentation",
+            "displayName": "Build CML and tests, and enable sanitizers",
             "steps": [
                 {
                     "type": "configure",

CONTRIBUTING.md

@@ -1,114 +1,5 @@
-# Contributing to the Common Model Library
+# Submitting Contributions
 
-The Common Model Library accepts new models and updates to existing models from NASA
-simulation-developing groups and any other groups to whom CML provides value. Before
-submitting changes, please look at our [coding standards](docs/CML_Coding_Standards.pdf)
-in the `docs` folder. If you're using an older version of CML, please also double check
-that the changes you're proposing have not already been integrated into CML in a more
-recent release.
-
-Proposed contributions should be submitted to CML in the form of a Pull Request in
-CML's [core repository](https://github.com/nasa/cml). When your change is ready
-for review by the CML team, take your pull request out of draft status. Each pull
-request should contain a cohesive, minimal set of changes to the CML codebase. If you
-are feeding back multiple unrelated changes to CML, please open multiple pull requests.
-This helps us review contributions faster and maintain a coherent Git history.
-
-CML maintains a robust testing pipeline which ensures that modifications to the code
-do not break existing functionality. Changes which result in a failed continuous
-integration (CI) pipeline will not be accepted under any circumstances.
-
-## Getting Access
-
-You must have a NASA identity to push to this repository. To obtain
-contributor privileges, fill out the
-[HQ AGCY NASA GitHub Collaborator](http://nams.nasa.gov/nams/asset/227756) request.
-For the business justification, state that you need contributor permissions for the
-cml repository. After that request is approved, you will have the ability to push
-changes to CML.
-
-If you do not have a NASA identity or do not wish to submit a GitHub Collaborator
-request, you may still contribute to CML. Create a
-[fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo)
-of this repository. You may push your changes to a branch inside your forked CML
-repository. When your changes are ready for review, you may open a pull request in
-your fork which targets the core CML repository. For more information, see GitHub's
-[guide](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork)
-to creating pull requests from forked repositories.
-
-## Submitting a Change to an Existing Model
-
-When submitting a change to an existing model, be aware that your changes may impact
-other CML-using groups. As such, large API or infrastructure changes may take a
-significant time to be approved. If the impact to other CML-using groups is deemed
-too great without sufficient rationale, the requested change may be rejected.
-
-Any changes you submit must be accompanied by changes to the model's documentation
-that accurately reflect the new state of the model. If you added new lines of code to
-a model, you must provide evidence that statement coverage of the model's tests
-continue to cover at least 90% of lines in the source code. New functionality must
-be covered by at least one test.
-
-## Submitting a New Model
-
-When submitting a new model to CML, you must provide:
-- The NASA NPR 7150.2 classification of the model.
-- Evidence of NASA-STD-7009 compliance.
-- The name of the originating group and a point of contact.
-
-Models must meet NPR 7150.2 Class A, B, C, or D to be accepted into CML. Additionally,
-all new models must have unit tests which cover at least 90% of source code lines and
-must be submitted alongside documentation which adequately describes the model. See the [coding standards](docs/CML_Coding_Standards.pdf) for more information.
-
-Models must also provide sufficient value to CML to be accepted. Trivial models which
-contain only a handful of lines of code can add a large maintenance burden to the CML team
-while providing little benefit to the project. Models which are very restrictive in their
-usage or make a large number of assumptions may be generic in theory, but in practice
-may only be useful for a single program. Lastly, please check whether the model you're
-providing is already provided by the C++ standard library or open-source projects such
-as [Boost](https://www.boost.org/), [Abseil](https://abseil.io/), and
-[Eigen](https://libeigen.gitlab.io/).
-
-Any change to CML that modifies project dependencies may be rejected if that change is not
-sufficiently in the interest of the user base. CML dependencies must be trusted, stable,
-and contain permissive licensing for distribution.
-
-To reduce the number of reviews by the CML team, we ask that models which are in active
-development not be submitted to CML unless the model is urgently needed by another group.
-In most cases, models in CML should be in a relatively stable state and should have
-undergone prior verification and validation.
-
-### By Submitting Your Model to CML, You Agree to the Following
-
-When you submit a model to CML, you waive any right to object to stylistic changes that
-CML may make to better integrate your model into our codebase. These changes may
-include, but are not limited to:
-- Renaming your model or recategorizing it into a different subdirectory.
-- Changing the formatting of your source code.
-- Changing the naming convention used for variables, types, and functions.
-- Moving some or all of your code into a different namespace.
-
-CML may also make non-breaking changes to your model without consulting you, such as:
-- Modifying the unit tests or adding new tests.
-- Updating the documentation that you provided.
-- Modernizing your code when we upgrade our minimum supported C++ standard.
-
-We ask that you provide an originating group and a point of contact when submitting
-your model because we will attempt to consult you when someone outside your group
-proposes a change to your model.
-
-## Artificial Intelligence (AI) Policy
-
-The CML team supports the responsible usage of AI assistance for software development.
-You may use AI tools when contributing to CML, subject to the following guidelines:
-- Pull requests, issues, comments, and any other submission to the CML GitHub
-  repository must be authored by a human. AI tools are not permitted to automatically
-  open an issue or respond to a pull request review.
-- A pull request must be fully understood by the human author who submits it.
-- AI tools are not permitted to be credited as authors. An AI tool may not be listed as
-  the co-author of a commit, the author of a change to documentation, or an author in
-  the Trick header of a source file, for example.
-
-Before marking a pull request as ready for review, please ensure that any AI-generated
-code, documentation, and tests adhere to our contribution guidelines and coding
-standards.
+Please see our [contributing guide](https://nasa.github.io/cml/contributing/contributing.html) for information on
+submitting new models or changes to existing models to CML. In the contributing guide, you can also find our coding
+standards, AI usage guidelines, and information on getting developer access to the CML repository if you have a NASA identity.