New documentation templating

Author: Jonas Berg

.gitignore

@@ -6,6 +6,9 @@ CMakeCache.txt
 install
 docs/_build
 
+# Python files
+*env*
+
 .cproject
 .project
 .dir-locals.el

docs/CMakeLists.txt

@@ -22,7 +22,7 @@ if (DOXYGEN_FOUND)
 
   # Doxygen configuration
   set(DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES)
-  set(DOXYGEN_TYPEDEF_HIDES_STRUCT NO)
+  set(DOXYGEN_TYPEDEF_HIDES_STRUCT YES)
   set(DOXYGEN_EXTRACT_ALL YES)
   set(DOXYGEN_EXTRACT_STATIC YES)
   set(DOXYGEN_STRIP_CODE_COMMENTS NO)
@@ -74,4 +74,14 @@ if (SPHINX_FOUND AND DOXYGEN_FOUND)
   add_sphinx_builder(sphinx-spelling spelling)
   add_sphinx_builder(sphinx-linkcheck linkcheck)
 
+  # Zip the documentation
+  message("c-open revision: ${CANOPEN_GIT_REVISION}")
+  add_custom_command(
+    TARGET sphinx-html POST_BUILD
+    COMMAND zip -FS -r copen_docs_${CANOPEN_GIT_REVISION}.zip sphinx/html/ > /dev/null
+    COMMAND echo "The Sphinx HTML and ZIP files are located in ${CMAKE_CURRENT_BINARY_DIR}"
+    BYPRODUCTS ${CMAKE_CURRENT_BINARY_DIR}/copen_docs_${CANOPEN_GIT_REVISION}.zip
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    COMMENT "Zipping HTML documentation")
+
 endif()

docs/README.txt

@@ -0,0 +1,12 @@
+To build the documentation, it is important to use the sphinx-build script
+installed in your virtual environment.
+Use CMAKE_IGNORE_PATH to prevent cmake from using a script installed elsewhere
+
+Run these commands (adapt to your needs):
+
+python3 -m venv myvenv
+source myvenv/bin/activate
+pip3 install -r docs/requirements.txt
+
+cmake -B build -DCMAKE_IGNORE_PATH:PATH=$HOME/.local/bin
+cmake --build build/ --target sphinx-html

docs/api_reference.rst

@@ -23,30 +23,30 @@ Callbacks
 Structs
 --------
 
-.. doxygenstruct:: co_obj
+.. doxygenstruct:: co_obj_t
    :members:
    :undoc-members:
 
-.. doxygenstruct:: co_entry
+.. doxygenstruct:: co_entry_t
    :members:
    :undoc-members:
 
-.. doxygenstruct:: co_default
+.. doxygenstruct:: co_default_t
    :members:
    :undoc-members:
 
-.. doxygenstruct:: co_cfg
+.. doxygenstruct:: co_cfg_t
    :members:
    :undoc-members:
 
 Enums
 ------
 
-.. doxygenenum:: co_sdo_abort
-.. doxygenenum:: co_state
-.. doxygenenum:: co_nmt_cmd
-.. doxygenenum:: co_otype
-.. doxygenenum:: co_dtype
-.. doxygenenum:: od_event
-.. doxygenenum:: co_store
-.. doxygenenum:: co_mode
+.. doxygenenum:: co_sdo_abort_t
+.. doxygenenum:: co_state_t
+.. doxygenenum:: co_nmt_cmd_t
+.. doxygenenum:: co_otype_t
+.. doxygenenum:: co_dtype_t
+.. doxygenenum:: od_event_t
+.. doxygenenum:: co_store_t
+.. doxygenenum:: co_mode_t

docs/conf.py

@@ -6,22 +6,29 @@
 
 # -- Path setup --------------------------------------------------------------
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import pathlib
+import re
+import sys
+
+import os
 
 
+pathobj_docs_dir = pathlib.Path(__file__).parent.absolute()
+pathobj_rootdir = pathobj_docs_dir.parent.absolute()
+
 # -- Project information -----------------------------------------------------
 
+try:
+    cmakelists_contents = pathobj_rootdir.joinpath("CMakeLists.txt").read_text()
+    versiontext_match = re.search(r"CANOPEN VERSION ([\d.]*)", cmakelists_contents)
+    version = versiontext_match.group(1)
+except:
+    version = "unknown version"
+
 project = 'c-open'
-copyright = '2022, RT-Labs AB'
+copyright = '2023, RT-Labs AB'
 author = 'RT-Labs AB'
 
-
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -32,19 +39,19 @@
     "recommonmark",
     "sphinx_copybutton",
     "sphinx_jinja",
-    "sphinx_rtd_theme",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.graphviz",
     "sphinxcontrib.kroki",
     "sphinxcontrib.programoutput",
     "sphinxcontrib.spelling",
 ]
 
+
 # Spelling
 spelling_word_list_filename = "spelling-wordlist.txt"
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["../../_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -57,17 +64,28 @@
 
 # -- Options for HTML output -------------------------------------------------
 
-# TODO Fine-tune the CSS to adjust logo and API documentation appearance
-html_theme = "press"
+html_context = {
+   "default_mode": "light"
+}
+
+html_theme = "sphinx_book_theme"
+html_theme_options = {
+    "show_nav_level": 3,
+    "home_page_in_toc": True,
+    "use_repository_button": True,
+    "use_fullscreen_button": False,
+    "navbar_end": ["navbar-icon-links"],
+    "use_download_button": False,
+    "repository_url": "https://github.com/rtlabs-com/c-open",
+}
+
 html_last_updated_fmt = "%Y-%m-%d %H:%M"
 html_static_path = ["static"]
-html_logo = "illustrations/c-open.png"
+html_logo = "static/i/c-open.svg"
 html_show_sourcelink = False
-html_copy_sources = False
-html_show_sphinx = False
 
-html_css_files = [
-    "../../css/custom_rtd.css",
-    "css/fix_table_width.css",
-    "css/change_header_size.css",
-]
+if os.getenv("USE_EXTERNAL_CSS") is not None:
+    html_css_files = [
+        "https://rt-labs.com/content/themes/rtlabs2020/assets/css/style.css",
+        "https://rt-labs.com/content/themes/rtlabs2020/assets/css/rt_custom_sphinx.css",
+    ]

docs/dependencies.txt

@@ -0,0 +1,20 @@
+
+# Solve issue with missing bullet points
+# See https://stackoverflow.com/questions/67542699/readthedocs-sphinx-not-rendering-bullet-list-from-rst-file
+docutils==0.17.1
+
+# Use versions that fit the docutils version
+breathe==4.34.0
+codespell==2.2.2
+graphviz==0.20.1
+myst-parser==0.18.1
+recommonmark==0.7.1
+rst2pdf==0.99
+rstcloth==0.5.3
+sphinx_book_theme==1.0.1
+sphinx-copybutton==0.5.1
+sphinx-jinja==2.0.2
+Sphinx==5.3.0
+sphinxcontrib-kroki==1.3.0
+sphinxcontrib-programoutput==0.17
+sphinxcontrib-spelling==8.0.0