From f64a92aa5cc77a6a7eab06256199624a9c14c5a9 Mon Sep 17 00:00:00 2001 From: erki Date: Sat, 30 Dec 2023 17:34:59 +0000 Subject: [PATCH] Documentation engine support (#3) Now I wonder if we'll ever use it. Co-authored-by: erki Reviewed-on: https://git.skullnet.me/erki/skullc-peripherals/pulls/3 --- .gitea/workflows/ci.yml | 22 +++++++++++++++++ CMakeLists.txt | 5 ++++ Docs/CMakeLists.txt | 53 +++++++++++++++++++++++++++++++++++++++++ Docs/Doxyfile.in | 11 +++++++++ Docs/conf.py | 31 ++++++++++++++++++++++++ Docs/index.rst | 23 ++++++++++++++++++ Docs/messaging.rst | 17 +++++++++++++ Docs/peripherals.rst | 9 +++++++ Docs/threads.rst | 9 +++++++ Docs/utility.rst | 9 +++++++ cmake/FindSphinx.cmake | 11 +++++++++ 11 files changed, 200 insertions(+) create mode 100644 Docs/CMakeLists.txt create mode 100644 Docs/Doxyfile.in create mode 100644 Docs/conf.py create mode 100644 Docs/index.rst create mode 100644 Docs/messaging.rst create mode 100644 Docs/peripherals.rst create mode 100644 Docs/threads.rst create mode 100644 Docs/utility.rst create mode 100644 cmake/FindSphinx.cmake diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index 3a13f55..c689ae5 100644 --- a/.gitea/workflows/ci.yml +++ b/.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 python3 python3-pip + 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 diff --git a/CMakeLists.txt b/CMakeLists.txt index b47f745..21e7acd 100644 --- a/CMakeLists.txt +++ b/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 diff --git a/Docs/CMakeLists.txt b/Docs/CMakeLists.txt new file mode 100644 index 0000000..b0fe757 --- /dev/null +++ b/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}) diff --git a/Docs/Doxyfile.in b/Docs/Doxyfile.in new file mode 100644 index 0000000..e05a25b --- /dev/null +++ b/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@" diff --git a/Docs/conf.py b/Docs/conf.py new file mode 100644 index 0000000..715478a --- /dev/null +++ b/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" + diff --git a/Docs/index.rst b/Docs/index.rst new file mode 100644 index 0000000..d016b5f --- /dev/null +++ b/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` diff --git a/Docs/messaging.rst b/Docs/messaging.rst new file mode 100644 index 0000000..27f7558 --- /dev/null +++ b/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: diff --git a/Docs/peripherals.rst b/Docs/peripherals.rst new file mode 100644 index 0000000..37d46fb --- /dev/null +++ b/Docs/peripherals.rst @@ -0,0 +1,9 @@ + +Peripherals Library +================= + +.. doxygennamespace:: Peripherals + :project: SkullCPeripheralsLibrary + :content-only: + :members: + :undoc-members: diff --git a/Docs/threads.rst b/Docs/threads.rst new file mode 100644 index 0000000..34829fb --- /dev/null +++ b/Docs/threads.rst @@ -0,0 +1,9 @@ + +Threads Library +================= + +.. doxygennamespace:: Threads + :project: SkullCPeripheralsLibrary + :content-only: + :members: + :undoc-members: diff --git a/Docs/utility.rst b/Docs/utility.rst new file mode 100644 index 0000000..afde32b --- /dev/null +++ b/Docs/utility.rst @@ -0,0 +1,9 @@ + +Utility Library +================= + +.. doxygennamespace:: Utility + :project: SkullCPeripheralsLibrary + :content-only: + :members: + :undoc-members: diff --git a/cmake/FindSphinx.cmake b/cmake/FindSphinx.cmake new file mode 100644 index 0000000..976a458 --- /dev/null +++ b/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)