add ToC to pages & refactor docxyfile path

also updates CSS for sphinx and doxygen

Author: 2bndy5

Doxyfile renamed to docs/Doxyfile

@@ -49,7 +49,17 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = ./docs
+OUTPUT_DIRECTORY       = ./
+
+# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path.
+# Stripping is only done if one of the specified strings matches the left-hand part
+# of the path. The tag can be used to show relative paths in the file list.
+# If left blank the directory from which doxygen is run is used as the path to strip.
+# Note that you can specify absolute paths here, but also relative paths, which will
+# be relative from the directory where doxygen is started.
+#
+# This tag requires that the tag FULL_PATH_NAMES is set to YES. 
+STRIP_FROM_PATH        = ../
 
 # Doxygen selects the parser to use depending on the extension of the files it
 # parses. With this tag you can assign which parser to use for a given
@@ -159,8 +169,8 @@ WARN_AS_ERROR          = YES
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = . \
-                         ./docs
+INPUT                  = .. \
+                         ./
 
 # If the value of the INPUT tag contains directories, you can use the
 # EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude
@@ -176,8 +186,8 @@ EXCLUDE_PATTERNS       = bcm2835* \
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           = examples \
-                         examples_RPi
+EXAMPLE_PATH           = ../examples \
+                         ../examples_RPi
 
 # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be
 # searched for input files to be used with the \include or \dontinclude commands
@@ -190,14 +200,14 @@ EXAMPLE_RECURSIVE      = YES
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             = images
+IMAGE_PATH             = ../images
 
 # If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that
 # is part of the input, its contents will be placed on the main page
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = ./docs/main_page.md
+USE_MDFILE_AS_MAINPAGE = main_page.md
 
 #---------------------------------------------------------------------------
 # Configuration options related to the HTML output
@@ -216,6 +226,24 @@ USE_MDFILE_AS_MAINPAGE = ./docs/main_page.md
 
 HTML_EXTRA_STYLESHEET  = doxygen-custom.css
 
+# The HTML_COLORSTYLE tag can be used to specify if the generated HTML output should be rendered
+# with a dark or light theme.
+#
+# Possible values are:
+# - LIGHT always generate light mode output
+# - DARK always generate dark mode output
+# - AUTO_LIGHT automatically set the mode according to the user preference,
+#   use light mode if no preference is set (the default)
+# - AUTO_DARK automatically set the mode according to the user preference,
+#   use dark mode if no preference is set
+# - TOGGLE allow to user to switch between light and dark mode via a button.
+#
+# The default value is: AUTO_LIGHT.
+#
+# This tag requires that the tag GENERATE_HTML is set to YES.
+
+HTML_COLORSTYLE = TOGGLE
+
 # If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML
 # page will contain the date and time when the page was generated. Setting this
 # to YES can help to show when doxygen was last run and thus if the

docs/addressing.md

@@ -1,4 +1,7 @@
 # Addressing Format: Understanding Addressing and Topology
+
+@tableofcontents
+
 <!-- markdownlint-disable MD033 MD032 -->
 An overview of addressing in RF24Network
 

docs/advanced_config.md

@@ -1,4 +1,7 @@
 # Advanced Configuration
+
+@tableofcontents
+
 <!-- markdownlint-disable MD033 -->
 RF24Network offers many features, some of which can be configured by editing the RF24Network_config.h file
 

docs/doxygen-custom.css

@@ -0,0 +1,3 @@
+table.markdownTable th {
+  color: unset;
+}

docs/main_page.md

@@ -1,5 +1,7 @@
 # Network Layer for RF24 Radios
 
+@tableofcontents
+
 This class implements an [OSI Network Layer](http://en.wikipedia.org/wiki/Network_layer) using nRF24L01(+) radios driven
 by the newly optimized [RF24 library fork](http://nRF24.github.com/RF24/).
 

docs/sphinx/_static/custom_material.css

@@ -1,69 +1,13 @@
-.md-typeset .admonition,
-.md-typeset details {
-  font-size: 0.75rem;
-}
-
-.md-typeset .admonition.tip>.admonition-title::before,
-.md-typeset .admonition.hint>.admonition-title::before {
-  mask-image: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12,3L1,9L12,15L21,10.09V17H23V9M5,13.18V17.18L12,21L19,17.18V13.18L12,17L5,13.18Z" /></svg>');
-}
-
-.md-typeset .admonition.seealso>.admonition-title::before {
-  mask-image: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M572.52 241.4C518.29 135.59 410.93 64 288 64S57.68 135.64 3.48 241.41a32.35 32.35 0 0 0 0 29.19C57.71 376.41 165.07 448 288 448s230.32-71.64 284.52-177.41a32.35 32.35 0 0 0 0-29.19zM288 400a144 144 0 1 1 144-144 143.93 143.93 0 0 1-144 144zm0-240a95.31 95.31 0 0 0-25.31 3.79 47.85 47.85 0 0 1-66.9 66.9A95.78 95.78 0 1 0 288 160z"/></svg>');
-  background-color: hsl(301, 100%, 63%);
-}
-
-.md-typeset .admonition.seealso {
-  border-left: .2rem solid hsl(301, 100%, 63%);
-}
-
-.md-typeset .admonition.seealso>.admonition-title {
-  background-color: hsla(287, 100%, 63%, 0.25);
-}
-
-.md-typeset .admonition.important>.admonition-title::before {
-  mask-image: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path d="M256 8C119.043 8 8 119.083 8 256c0 136.997 111.043 248 248 248s248-111.003 248-248C504 119.083 392.957 8 256 8zm0 110c23.196 0 42 18.804 42 42s-18.804 42-42 42-42-18.804-42-42 18.804-42 42-42zm56 254c0 6.627-5.373 12-12 12h-88c-6.627 0-12-5.373-12-12v-24c0-6.627 5.373-12 12-12h12v-64h-12c-6.627 0-12-5.373-12-12v-24c0-6.627 5.373-12 12-12h64c6.627 0 12 5.373 12 12v100h12c6.627 0 12 5.373 12 12v24z"/></svg>');
-  background-color: hsl(123, 100%, 63%);
-}
-
-.md-typeset .admonition.important {
-  border-left: .2rem solid hsl(123, 100%, 63%);
-}
-
-.md-typeset .admonition.important>.admonition-title {
-  background-color: hsla(123, 100%, 63%, 0.25);
-}
-
-.md-typeset .admonition.warning>.admonition-title::before {
-  background-color: hsl(0, 100%, 63%);
-}
-
-.md-typeset .admonition.warning {
-  border-left: .2rem solid hsl(0, 100%, 63%);
-}
-
-.md-typeset .admonition.warning>.admonition-title {
-  background-color: hsla(0, 100%, 63%, 0.25);
-}
-
 html .md-nav--primary .md-nav__title--site .md-nav__button {
   top: 0;
   left: 0;
   width: inherit;
   height: auto;
 }
 
-.md-typeset table:not([class]) th {
-  background-color: rgba(23, 35, 83, 0.8);
-}
-
-.md-typeset table:not([class]) tr:hover {
-  background-color: rgba(56, 2, 81, 0.8);
-  box-shadow: inset 0 .05rem 0 #9515ff;
-}
-
-[data-md-color-scheme="default"] {
-  --md-code-bg-color: #e8e7e7;
+thead {
+	background-color: var(--md-default-fg-color--light);
+	color: var(--md-primary-bg-color);
 }
 
 .md-nav__title .md-nav__button.md-logo img, .md-nav__title .md-nav__button.md-logo svg {
@@ -74,25 +18,3 @@ html .md-nav--primary .md-nav__title--site .md-nav__button {
 .md-header__button.md-logo img, .md-header__button.md-logo svg {
   width: auto;
 }
-
-.linenos {
-	background-color: var(--md-default-bg-color--light);
-	margin-right: 0.5rem;
-}
-
-/* CSS for Remark admonitions (translated by breathe from doxygen's @remark(s) cmd */
-:root {
-  --md-admonition-icon--remark: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 0 24 24" width="24px"><path d="M0 0h24v24H0z" fill="none"/><path d="M19 3H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2zm-5 14H7v-2h7v2zm3-4H7v-2h10v2zm0-4H7V7h10v2z"/></svg>')
-}
-.md-typeset .admonition.remark {
-  border-color: rgb(116, 66, 255);
-}
-.md-typeset .remark > .admonition-title {
-  background-color: rgba(116, 66, 255, 0.1);
-  border-color: rgb(116, 66, 255);
-}
-.md-typeset .remark > .admonition-title::before {
-  background-color: rgb(116, 66, 255);
-  -webkit-mask-image: var(--md-admonition-icon--remark);
-        mask-image: var(--md-admonition-icon--remark);
-}

docs/sphinx/conf.py

@@ -81,7 +81,7 @@
 READTHEDOCS = os.environ.get("READTHEDOCS", None) == "True"
 
 if READTHEDOCS:
-    subprocess.call("cd ../..; doxygen", shell=True)
+    subprocess.call("cd ..; doxygen", shell=True)
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -136,6 +136,32 @@
     ("cpp:function", dict(include_fields_in_toc=False)),
 ]
 
+sphinx_immaterial_custom_admonitions = [
+    {
+        "name": "warning",
+        "color": (255, 66, 66),
+        "icon": "octicons/alert-24",
+        "override": True,
+    },
+    {
+        "name": "note",
+        "icon": "octicons/pencil-24",
+        "override": True,
+    },
+    {
+        "name": "seealso",
+        "color": (255, 66, 252),
+        "icon": "octicons/eye-24",
+        "title": "See Also",
+        "override": True,
+    },
+    {
+        "name": "remark",
+        "color": (116, 66, 255),
+        "icon": "octicons/checklist-16",
+    },
+]
+
 # Set link name generated in the top bar.
 html_title = "RF24Network C++ library"
 

docs/tuning.md

@@ -1,4 +1,7 @@
 # Performance and Data Loss: Tuning the Network
+
+@tableofcontents
+
 <!-- markdownlint-disable MD031-->
 Tips and examples for tuning the network and general operation.
 
@@ -44,7 +47,7 @@ In RF24Network, the master is just `00`
 
 ## Multicast
 
-Multicast is enabled by default, which limits the master node to 5 child pipes and other nodes to 4. Nodes are 
+Multicast is enabled by default, which limits the master node to 5 child pipes and other nodes to 4. Nodes are
 arranged in multicast 'levels' with the master node being level 0, nodes 01-05 are level 1, nodes n1-n5 are level 2,
 and so on. The multicast level of each node can be configured as desired by the user, or multicast can be
 disabled by editing RF24Network_config.h. For example, if all nodes are in range of the master node, all nodes can

docs/zigabee.md

@@ -1,5 +1,7 @@
 # Comparison to ZigBee
 
+@tableofcontents
+
 This network layer is influenced by the design of ZigBee, but does not implement it
 directly.