Merge pull request #158 from nasa-jpl/pastord-update-readme

Update readme, refactor fcviz

Author: PastorD

.doxyfile.in

@@ -32,26 +32,26 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "JSD"
+PROJECT_NAME           = "@PROJECT_NAME@"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = @JSD_VERSION@
+PROJECT_NUMBER         = @PROJECT_VERSION@
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          = "JPL SOEM Drivers"
+PROJECT_BRIEF          = "@PROJECT_DESCRIPTION@"
 
 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # in the documentation. The maximum height of the logo should not exceed 55
 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
 # the logo to the output directory.
 
-PROJECT_LOGO           = ../doc/img/JPL-logo-color.png
+PROJECT_LOGO           = @CMAKE_SOURCE_DIR@/doc/img/JPL-logo-color.png
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
 # into which the generated documentation will be written. If a relative path is
@@ -152,7 +152,7 @@ FULL_PATH_NAMES        = YES
 # will be relative from the directory where doxygen is started.
 # This tag requires that the tag FULL_PATH_NAMES is set to YES.
 
-STRIP_FROM_PATH        =
+STRIP_FROM_PATH        = @CMAKE_SOURCE_DIR@
 
 # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
 # path mentioned in the documentation of a class, which tells the reader which
@@ -771,7 +771,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../src
+INPUT                  = @CMAKE_SOURCE_DIR@/src @CMAKE_SOURCE_DIR@/README.md @CMAKE_SOURCE_DIR@/doc
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -865,7 +865,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             =
+IMAGE_PATH             = @CMAKE_SOURCE_DIR@/doc/img
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -921,7 +921,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = README.md
+USE_MDFILE_AS_MAINPAGE = @CMAKE_SOURCE_DIR@/README.md
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing

.github/workflows/docs.yml

@@ -0,0 +1,70 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - ".doxyfile.in"
+      - "CMakeLists.txt"
+      - "README.md"
+      - "doc/**"
+      - "src/**"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    paths:
+      - ".doxyfile.in"
+      - "CMakeLists.txt"
+      - "README.md"
+      - "doc/**"
+      - "src/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+    inputs:
+      deploy:
+        description: "Deploy the generated docs to GitHub Pages"
+        required: false
+        default: false
+        type: boolean
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install documentation dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y doxygen graphviz libyaml-cpp-dev
+      - name: Configure CMake
+        run: cmake -S . -B build -DBUILD_TESTS=OFF
+      - name: Build documentation
+        run: cmake --build build --target doc
+      - name: Upload Pages artifact
+        if: (github.event_name == 'push' && github.ref == 'refs/heads/master') || (github.event_name == 'workflow_dispatch' && inputs.deploy)
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: build/doxygen_html
+
+  deploy:
+    needs: build
+    if: (github.event_name == 'push' && github.ref == 'refs/heads/master') || (github.event_name == 'workflow_dispatch' && inputs.deploy)
+    runs-on: ubuntu-24.04
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/configure-pages@v5
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -11,15 +11,38 @@ To learn more about fastcat, checkout the following documents:
 - 2021 Aeroconf paper submission `Fastcat: An Open-Source Library for Composable
   EtherCAT Control Systems`
 - README for build details
-- The API documentation (build locally using doxygen - Github hosting still a work-in-progress)
+- The API documentation
 
 ### Prerequisites
 
-Fastcat has ben tested on Ubuntu 20.04, though it should work on older versions of Ubuntu with minor revisions to these steps. 
+Fastcat has been tested on Ubuntu 20.04, 22.04 and 24.04, though it should work on older versions of Ubuntu with minor revisions to these steps.
 
 ```bash
-$ sudo apt install libyaml-cpp-dev libreadline-dev doxygen python3-pip
-$ sudo pip3 install pyaml cogapp graphviz ipython==7.9
+$ sudo apt install libyaml-cpp-dev libreadline-dev doxygen graphviz
+```
+
+The `fcviz` utility is configured as a `uv` script, so its Python dependencies do not need to be installed globally:
+
+Install `uv` using Astral's official installer:
+
+```bash
+$ curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Installation options and other platforms are documented by Astral at <https://docs.astral.sh/uv/getting-started/installation/>.
+
+```bash
+$ uv run fcviz/fcviz.py example_configs/paper_examples/paper_faulter_config.yaml
+```
+
+If you do not want to use `uv`, check the inline dependency metadata at the top of `fcviz/fcviz.py` and install those packages in your preferred Python environment before running the script directly.
+
+If you need to regenerate code with `fcgen`, install Ubuntu's `python3-cogapp` package. On some systems, you may need to enable the `universe` repository first:
+
+```bash
+$ sudo add-apt-repository universe
+$ sudo apt update
+$ sudo apt install python3-cogapp
 ```
 
 ### Building
@@ -51,14 +74,14 @@ $ make memcheck  # note valgrind is required to perform memory checking
 ```bash
 # Install dependencies for Ubuntu
 $ sudo apt install doxygen graphviz
-
-# use the build system to generate the code for you!
 $ cd build
 $ make doc
 ```
 
 The output documentation is created in the directory `doxygen_html` and can be opened by any web browser from the root `index.html` webpage.
 
+The repository also includes a GitHub Actions workflow that builds this `doc` target and publishes it to GitHub Pages on pushes to `master`. Once GitHub Pages is enabled for the repository with GitHub Actions as the source, the published site will be available at <https://nasa-jpl.github.io/fastcat/>.
+
 ### Using fastcat in your Project
 
 We recommend using the CMake `FetchContent` utility to acquire fastcat and its upstream dependencies.
@@ -67,12 +90,12 @@ We recommend using the CMake `FetchContent` utility to acquire fastcat and its u
 include(FetchContent)
 FetchContent_Declare(fastcat
     GIT_REPOSITORY git@github.com:nasa-jpl/fastcat.git
-    GIT_TAG v0.4.3
+    GIT_TAG v0.13.13
     )
 FetchContent_MakeAvailable(fastcat)
 ```
 
-It is always recommend you specify your dependency to a tagged reldroppingease (`GIT_TAG v0.4.3`) so updates to master cannot break your build (NOT `GIT_TAG master`). 
+It is always recommend you specify your dependency to a tagged reldroppingease (`GIT_TAG v0.13.13`) so updates to master cannot break your build (NOT `GIT_TAG master`). 
 
 ### Semantic Versioning
 
@@ -83,8 +106,3 @@ fastcat uses Semantic versioning to help applications reason about the software
 * Patch Versions will denote bug fixes or minor improvements and will not break user applications.
 
 Violations of these rules will be considered errors and should be patched immediately. Please open an issue if you find a violation.
-
-**Note**
-
-Major version `0` indicates the API is still considered experimental and subject to change with any new release. These rules will be strictly followed after a Major version `1` release. 
-

doc/fastcat_primer.md

@@ -117,7 +117,7 @@ This example can be recreated with the following command:
 
 ``` bash
 !$ cd </path/to/fastcat>
-$ python3 fcviz/fcviz.py example_configs/paper_examples/paper_faulter_config.yaml
+$ uv run fcviz/fcviz.py example_configs/paper_examples/paper_faulter_config.yaml
 ```