From 83521b3a2e4acb4ca67c55a297636726b5069741 Mon Sep 17 00:00:00 2001 From: Lukas Woodtli Date: Thu, 1 Feb 2024 08:46:09 +0100 Subject: [PATCH] Introduce Sphinx for documentation The basic infrastructure for writing documentation using Sphinx is added. --- .github/workflows/sphinx.yaml | 36 +++++++++++++++++++++++++++++++++++ doc/sphinx/conf.py | 30 +++++++++++++++++++++++++++++ doc/sphinx/index.rst | 17 +++++++++++++++++ doc/sphinx/logging.rst | 2 ++ doc/sphinx/make.bat | 35 ++++++++++++++++++++++++++++++++++ doc/sphinx/requirements.txt | 2 ++ 6 files changed, 122 insertions(+) create mode 100644 .github/workflows/sphinx.yaml create mode 100644 doc/sphinx/conf.py create mode 100644 doc/sphinx/index.rst create mode 100644 doc/sphinx/logging.rst create mode 100644 doc/sphinx/make.bat create mode 100644 doc/sphinx/requirements.txt diff --git a/.github/workflows/sphinx.yaml b/.github/workflows/sphinx.yaml new file mode 100644 index 000000000..68e2a8b2b --- /dev/null +++ b/.github/workflows/sphinx.yaml @@ -0,0 +1,36 @@ +name: Build Documentation + +on: [push, pull_request] + +jobs: + sphinx: + runs-on: ubuntu-22.04 + + steps: + - name: Checkout code including full history and submodules + uses: actions/checkout@v3 + with: + submodules: true + fetch-depth: 0 + + - name: Install dependencies from APT repository + run: | + sudo apt-get update + sudo apt-get install cmake ninja-build + + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r doc/sphinx/requirements.txt + + - name: Build Sphinx documentation + run: | + sphinx-build -M html sphinx sphinx_output + working-directory: doc/ + + - name: Upload HTML documentation + uses: actions/upload-artifact@v1 + with: + name: Documentation (HTML) + path: doc/sphinx_output/html diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py new file mode 100644 index 000000000..aa3bbe6bd --- /dev/null +++ b/doc/sphinx/conf.py @@ -0,0 +1,30 @@ +# 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 = 'Wakaama' +copyright = '2024, Lukas Woodtli' +author = 'Lukas Woodtli' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ['literate_sphinx'] + +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 = 'alabaster' + +# -- Options for literate_sphinx ---------------------------------------------- + + diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst new file mode 100644 index 000000000..d097677a9 --- /dev/null +++ b/doc/sphinx/index.rst @@ -0,0 +1,17 @@ +Welcome to Wakaama +================== + +Wakaama is a C library for the LwM2M protocol. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/sphinx/logging.rst b/doc/sphinx/logging.rst new file mode 100644 index 000000000..892c29479 --- /dev/null +++ b/doc/sphinx/logging.rst @@ -0,0 +1,2 @@ +Logging +------- \ No newline at end of file diff --git a/doc/sphinx/make.bat b/doc/sphinx/make.bat new file mode 100644 index 000000000..954237b9b --- /dev/null +++ b/doc/sphinx/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/doc/sphinx/requirements.txt b/doc/sphinx/requirements.txt new file mode 100644 index 000000000..9f4eb67f3 --- /dev/null +++ b/doc/sphinx/requirements.txt @@ -0,0 +1,2 @@ +literate-sphinx==0.1.3 +Sphinx==7.2.6