Update HTML theme

Author: Jonas Berg

.gitignore

@@ -10,6 +10,13 @@ doc/_copied
 .cproject
 .project
 
+
+# Python files
+docs/.mypy_cache/
+docs/_generated/
+docs/__pycache__/
+*venv*
+
 # Object files
 *.o
 *.ko

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,34 +67,37 @@
     '.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 = {
-    "analytics_id": "G-378E9EVTG5",
-    "display_version": True,
-    "navigation_depth": 2,
+    "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/p-nbet",
 }
 
 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