Update HTML theme

Author: Jonas Berg

.github/workflows/build.yml

@@ -17,7 +17,7 @@ jobs:
         run: sudo apt-get install doxygen libsnmp-dev python3-pip texlive-latex-recommended texlive-fonts-recommended tex-gyre texlive-latex-extra latexmk
 
       - name: Install Python dependencies
-        run: pip3 install -r ${{github.workspace}}/doc/doc_requirements.txt
+        run: pip3 install -r ${{github.workspace}}/doc/requirements.txt
 
       - name: Show Python dependencies
         run: pip3 freeze

.gitignore

@@ -10,6 +10,10 @@ doc/_copied
 .cproject
 .project
 
+
+# Python files
+*env*
+
 # Object files
 *.o
 *.ko

doc/CMakeLists.txt

@@ -87,6 +87,17 @@ if (SPHINX_FOUND AND DOXYGEN_FOUND)
   add_sphinx_builder(sphinx-spelling spelling)
   add_sphinx_builder(sphinx-linkcheck linkcheck)
   add_sphinx_builder(sphinx-pdf latexpdf)
+  add_dependencies(sphinx-html remove_badge_svg_images)
   add_dependencies(sphinx-pdf remove_badge_svg_images)
 
+    # Zip the documentation
+  message("p-net revision: ${PROFINET_GIT_REVISION}")
+  add_custom_command(
+    TARGET sphinx-html POST_BUILD
+    COMMAND zip -FS -r pnet_docs_${PROFINET_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}/pnet_docs_${PROFINET_GIT_REVISION}.zip
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    COMMENT "Zipping HTML documentation")
+
 endif()

doc/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 doc/requirements.txt
+
+cmake -B build -DCMAKE_IGNORE_PATH:PATH=$HOME/.local/bin
+cmake --build build/ --target sphinx-html

doc/conf.py

@@ -4,6 +4,8 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+
+import os
 import pathlib
 import re
 import sys
@@ -14,10 +16,6 @@
 # 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('.'))
 
 pathobj_docs_dir = pathlib.Path(__file__).parent.absolute()
 pathobj_rootdir = pathobj_docs_dir.parent.absolute()
@@ -42,16 +40,20 @@
 # ones.
 extensions = [
     "breathe",
-    "myst_parser",
-    "rst2pdf.pdfbuilder",
-    "sphinx_rtd_theme",
+    "recommonmark",
+    "sphinx_copybutton",
+    "sphinx_jinja",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.graphviz",
+    "sphinxcontrib.kroki",
+    "sphinxcontrib.programoutput",
     "sphinxcontrib.spelling",
 ]
 
 needs_sphinx = "1.8"
 
 # 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.
@@ -65,19 +67,17 @@
     '.md': 'markdown',
 }
 
+breathe_projects = {project: "../build/doc/xml/"}
+breathe_default_project = project
 
-# -- Options for HTML output -------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = "sphinx_rtd_theme"
+# -- Options for HTML output -------------------------------------------------
 
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["static"]
+html_context = {
+   "default_mode": "light"
+}
 
+html_theme = "sphinx_book_theme"
 html_theme_options = {
     "show_nav_level": 3,
     "home_page_in_toc": True,
@@ -89,14 +89,15 @@
 }
 
 html_last_updated_fmt = "%Y-%m-%d %H:%M"
-breathe_projects = {project: "../build/doc/xml/"}
-breathe_default_project = project
-
-html_css_files = [
-    "../../css/custom_rtd.css",  # Requested by web developer
-    "css/fix_table_width.css",
-    "css/change_header_size.css",
-]
+html_static_path = ["static"]
+html_logo = "static/i/p-net.svg"
+html_show_sourcelink = False
+
+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",
+    ]
 
 
 # -- Options for PDF output -------------------------------------------------

doc/doc_requirements.txt

@@ -0,0 +1,19 @@
+# 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