Action to build docs

.gitea/workflows/ci.yml

@@ -28,3 +28,25 @@ jobs:
       - name: Run tests
         working-directory: ${{runner.workspace}}/build
         run: ctest . --output-on-failure
+  Docs:
+      runs-on: ubuntu-latest
+      steps:
+        - uses: actions/checkout@v3
+
+        - name: Prepare environment
+          run: |
+            apt update
+            apt install -y --no-install-recommends build-essential cmake ninja-build doxygen python3-sphinx
+            pip3 install breathe
+
+        - name: Configure build
+          working-directory: ${{runner.workspace}}
+          run: |
+            cmake . -B${{runner.workspace}}/build \
+                -G"Ninja" \
+                -DCMAKE_BUILD_TYPE=Release \
+                -DSKULLC_WITH_DOCS=ON
+
+        - name: Build docs
+          working-directory: ${{runner.workspace}}/build
+          run: ninja Sphinx

CMakeLists.txt

@@ -14,6 +14,7 @@ list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake/)
 
 option(SKULLC_WITH_TESTS "Enable unit testing." OFF)
 option(SKULLC_WITH_HAL "Enable the compiling and deployment of the HAL dependent sections." OFF)
+option(SKULLC_WITH_DOCS "Enable documentation building." OFF)
 
 include(skullc-install)
 
@@ -26,6 +27,10 @@ if(SKULLC_WITH_TESTS)
     add_subdirectory(Tests)
 endif()
 
+if(SKULLC_WITH_DOCS)
+    add_subdirectory(Docs)
+endif()
+
 ## Install
 
 configure_file(skullc-config.cmake

Docs/CMakeLists.txt

@@ -0,0 +1,53 @@
+find_package(Doxygen REQUIRED)
+find_package(Sphinx REQUIRED)
+
+file(GLOB_RECURSE SKULLC_PUBLIC_HEADERS
+        ${PROJECT_SOURCE_DIR}/Messaging/Inc/*
+        ${PROJECT_SOURCE_DIR}/Threads/Inc/*
+        ${PROJECT_SOURCE_DIR}/Utility/Inc/*
+        ${PROJECT_SOURCE_DIR}/Peripherals/Inc/*
+)
+
+set(DOXYGEN_INPUT_DIRS "${PROJECT_SOURCE_DIR}/Messaging/Inc ${PROJECT_SOURCE_DIR}/Threads/Inc ${PROJECT_SOURCE_DIR}/Utility/Inc ${PROJECT_SOURCE_DIR}/Peripherals/Inc")
+set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/docs/doxygen)
+set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/xml/index.xml)
+set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
+
+file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR}) #Doxygen won't create this for us
+add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}
+        DEPENDS ${SKULLC_PUBLIC_HEADERS}
+        COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
+        MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
+        COMMENT "Generating docs"
+)
+
+add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})
+
+set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
+set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
+set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
+file(GLOB SPHINX_RST_FILES ${SPHINX_SOURCE}/*.rst)
+
+# Only regenerate Sphinx when:
+# - Doxygen has rerun
+# - Our doc files have been updated
+# - The Sphinx config has been updated
+add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
+        COMMAND
+        ${SPHINX_EXECUTABLE} -b html
+        # Tell Breathe where to find the Doxygen output
+        -Dbreathe_projects.SkullCPeripheralsLibrary=${DOXYGEN_OUTPUT_DIR}/xml
+        ${SPHINX_SOURCE} ${SPHINX_BUILD}
+        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+        DEPENDS
+        # Other docs files you want to track should go here (or in some variable)
+        ${SPHINX_RST_FILES}
+        ${DOXYGEN_INDEX_FILE}
+        MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
+        COMMENT "Generating documentation with Sphinx")
+
+# Nice named target so we can run the job easily
+add_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})

Docs/Doxyfile.in

@@ -0,0 +1,11 @@
+// Every other setting ends up being default.
+
+GENERATE_XML = YES
+GENERATE_HTML = YES
+
+JAVADOC_AUTOBRIEF = YES
+
+INPUT = @DOXYGEN_INPUT_DIRS@
+RECURSIVE = YES
+
+OUTPUT_DIRECTORY = "@DOXYGEN_OUTPUT_DIR@"

Docs/conf.py

@@ -0,0 +1,31 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'SkullC Peripherals Library'
+copyright = '2023, Rusted Skull'
+author = 'Rusted Skull'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [ "breathe" ]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'classic'
+html_static_path = ['_static']
+
+# -- Breathe Configuration"
+breathe_default_project = "SkullCPeripheralsLibrary"
+

Docs/index.rst

@@ -0,0 +1,23 @@
+.. SkullC Peripherals Library documentation master file, created by
+   sphinx-quickstart on Thu Dec 28 23:16:21 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to SkullC Peripherals Library's documentation!
+======================================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   utility
+   peripherals
+   threads
+   messaging
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

Docs/messaging.rst

@@ -0,0 +1,17 @@
+
+Messaging Library
+=================
+
+A small Packet and Parser implementation for framing random message structures on the wire.
+
+Use the :cpp:struct:`Packet` to copy in various data. Then send the serialized version of the packet
+onto the wire.
+
+:cpp:class:`Messaging::Parser` will help you put bytes coming in from the wire into coherent packets, and will serve you
+these packets as you're ready for them.
+
+.. doxygennamespace:: Messaging
+   :project: SkullCPeripheralsLibrary
+   :content-only:
+   :members:
+   :undoc-members:

Docs/peripherals.rst

@@ -0,0 +1,9 @@
+
+Peripherals Library
+=================
+
+.. doxygennamespace:: Peripherals
+   :project: SkullCPeripheralsLibrary
+   :content-only:
+   :members:
+   :undoc-members:

Docs/threads.rst

@@ -0,0 +1,9 @@
+
+Threads Library
+=================
+
+.. doxygennamespace:: Threads
+   :project: SkullCPeripheralsLibrary
+   :content-only:
+   :members:
+   :undoc-members:

Docs/utility.rst

@@ -0,0 +1,9 @@
+
+Utility Library
+=================
+
+.. doxygennamespace:: Utility
+   :project: SkullCPeripheralsLibrary
+   :content-only:
+   :members:
+   :undoc-members:

cmake/FindSphinx.cmake

@@ -0,0 +1,11 @@
+#Look for an executable called sphinx-build
+find_program(SPHINX_EXECUTABLE
+        NAMES sphinx-build
+        DOC "Path to sphinx-build executable")
+
+include(FindPackageHandleStandardArgs)
+
+#Handle standard arguments to find_package like REQUIRED and QUIET
+find_package_handle_standard_args(Sphinx
+        "Failed to find sphinx-build executable"
+        SPHINX_EXECUTABLE)