docs: Use Doctools theme

Use Doctools directives/roles and "cosmic" theme.
Include requirements.txt file with the doc dependencies (sphinx,
doctools).
Update doc copyright year range.
Update pip and install newer versions of the requirements during
run_build.sh.
Remove adi_logo.png, since the theme already ships the org logo.

Signed-off-by: Jorge Marques <[email protected]>

ci/run_build.sh

@@ -84,7 +84,10 @@ build_drivers() {
 }
 
 build_documentation() {
-    sudo apt-get install -y graphviz python3-sphinx
+    sudo apt-get install -y graphviz python3-pip
+    # Install a recent version of pip and the requirements
+    pip3 install pip --upgrade
+    pip3 install -r ${TOP_DIR}/doc/sphinx/source/requirements.txt
     # Install a recent version of doxygen
 	DOXYGEN_URL="https://sourceforge.net/projects/doxygen/files/rel-1.8.17/doxygen-1.8.17.src.tar.gz/"
 	mkdir -p "${DEPS_DIR}"

doc/sphinx/source/conf.py

@@ -19,7 +19,7 @@
 
 repository = 'no-OS'
 project = 'no-OS'
-copyright = '2023, Analog Devices, Inc.'
+copyright = '2023-2024, Analog Devices, Inc.'
 author = 'Analog Devices, Inc.'
 
 
@@ -29,6 +29,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "adi_doctools"
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -45,11 +46,9 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'cosmic'
 
 # 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 = []
-
-html_logo = "adi_logo.png"

doc/sphinx/source/requirements.txt

@@ -0,0 +1,2 @@
+sphinx
+https://github.com/analogdevicesinc/doctools/releases/download/latest/adi-doctools.tar.gz