minor doc updates (#236)

- upgrades to doxygen v1.10.0 - adds custom CSS - set doxygen's favicon - fixes cross-link references
nRF24 · Apr 6, 2024 · 7c30deb · 7c30deb
1 parent 087af89
commit 7c30deb
Show file tree

Hide file tree

Showing 6 changed files with 121 additions and 13 deletions.
diff --git a/.github/workflows/doxygen.yml b/.github/workflows/doxygen.yml
@@ -36,4 +36,5 @@ jobs:
     uses: nRF24/.github/.github/workflows/build_docs.yaml@main
     with:
       deploy-gh-pages: ${{ github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/master') }}
+      doxygen-version: '1.10.0'
     secrets: inherit
diff --git a/docs/Doxyfile b/docs/Doxyfile
@@ -17,6 +17,8 @@
 # Project related configuration options
 #---------------------------------------------------------------------------
 
+PROJECT_ICON = sphinx/_static/new_favicon.ico
+
 # The PROJECT_NAME tag is a single word (or a sequence of words surrounded by
 # double-quotes, unless you are using Doxywizard) that should identify the
 # project for which the documentation is generated. This name is used in the
@@ -343,14 +345,15 @@ HTML_EXTRA_STYLESHEET  = doxygen-custom.css
 
 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
-# documentation is up to date.
+# If the TIMESTAMP tag is set different from NO then each generated page will contain
+# the date or date and time when the page was generated. Setting this to NO can help
+# when comparing the output of multiple runs.
+#
+# Possible values are: YES, NO, DATETIME and DATE.
+#
 # The default value is: NO.
-# This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_TIMESTAMP         = YES
+TIMESTAMP         = DATE
 
 # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML
 # documentation will contain a main index with vertical navigation menus that

diff --git a/docs/doxygen-custom.css b/docs/doxygen-custom.css
@@ -1,3 +1,107 @@
 table.markdownTable th {
   color: unset;
 }
+
+/* overrides from default CSSS for some admonitions */
+dl.note, dl.remark,
+dl.warning, dl.attention {
+  color: unset;
+}
+dl.remark {
+	background: var(--remark-color-bg);
+	border-left: 8px solid var(--remark-color-hl);
+}
+dl.remark dt {
+	color: var(--remark-color-hl);
+}
+
+/* special rules to accent `/see` or `/sa` command output */
+dl.see {
+	background: var(--seealso-color-bg);
+	border-left: 8px solid var(--seealso-color-hl);
+}
+dl.see dt {
+	color: var(--seealso-color-hl);
+}
+dl.see {
+  padding: 10px;
+	margin: 10px 0px;
+	overflow: hidden;
+	margin-left: 0;
+	border-radius: 4px;
+}
+
+/* admonition icons */
+dl.note dt::before {
+  background-color: var(--note-color-hl);
+  mask-image: var(--note-icon);
+}
+dl.see dt::before {
+  background-color: var(--seealso-color-hl);
+  mask-image: var(--seealso-icon);
+}
+dl.remark dt::before {
+  background-color: var(--remark-color-hl);
+  mask-image: var(--remark-icon);
+}
+dl.warning dt::before {
+  background-color: var(--warning-color-hl);
+  mask-image: var(--warning-icon);
+}
+dl.deprecated dt::before {
+  background-color: var(--deprecated-color-hl);
+  mask-image: var(--deprecated-icon);
+}
+dl.note dt::before,
+dl.see dt::before,
+dl.warning dt::before,
+dl.remark dt::before,
+dl.deprecated dt::before {
+	vertical-align: middle;
+	background-repeat: no-repeat;
+	content: "";
+	display: inline-block;
+	height: 2em;
+	width: 2em;
+  margin-right: 0.25rem;
+}
+dl.note dt,
+dl.see dt,
+dl.warning dt,
+dl.remark dt,
+dl.deprecated dt {
+  margin-top: -0.35em;
+  margin-bottom: 0.5em;
+}
+
+/* icon SVG data */
+*:root {
+  --note-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path d="M200-200h57l391-391-57-57-391 391v57Zm-80 80v-170l528-527q12-11 26.5-17t30.5-6q16 0 31 6t26 18l55 56q12 11 17.5 26t5.5 30q0 16-5.5 30.5T817-647L290-120H120Zm640-584-56-56 56 56Zm-141 85-28-29 57 57-29-28Z"/></svg>');
+  --seealso-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path d="M480-320q75 0 127.5-52.5T660-500q0-75-52.5-127.5T480-680q-75 0-127.5 52.5T300-500q0 75 52.5 127.5T480-320Zm0-72q-45 0-76.5-31.5T372-500q0-45 31.5-76.5T480-608q45 0 76.5 31.5T588-500q0 45-31.5 76.5T480-392Zm0 192q-146 0-266-81.5T40-500q54-137 174-218.5T480-800q146 0 266 81.5T920-500q-54 137-174 218.5T480-200Zm0-300Zm0 220q113 0 207.5-59.5T832-500q-50-101-144.5-160.5T480-720q-113 0-207.5 59.5T128-500q50 101 144.5 160.5T480-280Z"/></svg>');
+  --warning-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path d="m40-120 440-760 440 760H40Zm138-80h604L480-720 178-200Zm302-40q17 0 28.5-11.5T520-280q0-17-11.5-28.5T480-320q-17 0-28.5 11.5T440-280q0 17 11.5 28.5T480-240Zm-40-120h80v-200h-80v200Zm40-100Z"/></svg>');
+  --remark-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path d="M382-240 154-468l57-57 171 171 367-367 57 57-424 424Z"/></svg>');
+  --deprecated-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path d="M280-120q-33 0-56.5-23.5T200-200v-520h-40v-80h200v-40h240v40h200v80h-40v520q0 33-23.5 56.5T680-120H280Zm400-600H280v520h400v-520ZM360-280h80v-360h-80v360Zm160 0h80v-360h-80v360ZM280-720v520-520Z"/></svg>');
+}
+
+/* color overrides */
+html {
+  /* light theme CSS variables */
+  --note-color-bg: hsla(47.6, 77.3%, 91.4%, 65%);
+  --warning-color-bg: hsla(6.8, 75.9%, 88.6%, 65%);
+  --deprecated-color-bg: hsla(205.7, 22.6%, 93.9%, 65%);
+  --seealso-color-bg: hsla(215, 76%, 89%, 65%);
+  --seealso-color-hl: hsl(215, 98%, 48%);
+  --remark-color-bg: hsla(133, 75%, 89%, 65%);
+  --remark-color-hl: hsl(133, 98.9%, 35.3%);
+}
+
+html.dark-mode {
+  /* dark theme CSS variables */
+  --note-color-bg: hsla(45.8, 87.3%, 12.4%, 65%);
+  --warning-color-bg: hsla(5.2, 33.3%, 13.5%, 65%);
+  --deprecated-color-bg: hsla(221.5, 12.4%, 20.6%, 65%);
+  --seealso-color-bg: hsla(215, 33%, 14%, 0.65);
+  --seealso-color-hl: hsl(215, 98%, 48%);
+  --remark-color-bg: hsla(133, 32%, 14%, 65%);
+  --remark-color-hl: hsl(133, 98%, 48%);
+}
diff --git a/docs/general_usage.md b/docs/general_usage.md
@@ -6,7 +6,7 @@
 
 1. **Static Network** (No Mesh)
 
-   RF24Network can be configured manually, with a static design. RF24Mesh is not used at all. See [Network addressing](http://nRF24.github.io/RF24Network/md_docs_addressing.html)
+   RF24Network can be configured manually, with a static design. RF24Mesh is not used at all. See [Network addressing](http://nRF24.github.io/RF24Network/md_docs_2addressing.html)
 2. **Static Network w/Dynamic Assignment**
 
    RF24Mesh is only used to acquire an address on startup. Nodes are generally expected to remain stationary. Changes to

diff --git a/docs/main_page.md b/docs/main_page.md
@@ -80,8 +80,8 @@ multi-node radio network.
 ## How to learn more
 
 - Try it out!
-- [Setup and Configuration](md_docs_setup_config.html)
-- [Usage & Overview](md_docs_general_usage.html)
+- [Setup and Configuration](setup_config.md)
+- [Usage & Overview](general_usage.md)
 - [RF24Mesh Class Documentation](classRF24Mesh.html)
 - [RF24 Network Class Documentation](http://nRF24.github.io/RF24Network/)
 - [RF24Ethernet: TCP/IP based Mesh over RF24](http://nRF24.github.io/RF24Ethernet/)

diff --git a/docs/setup_config.md b/docs/setup_config.md
@@ -29,10 +29,10 @@ connected together.
 2. Configure and test the hardware using examples from RF24 and RF24Network prior to attempting to use RF24Mesh
    - In Arduino IDE
       - File > Examples > RF24 > GettingStarted
-        @see [Arduino Support page](http://nRF24.github.io/RF24/md_docs_arduino.html)
+        @see [Arduino Support page](http://nRF24.github.io/RF24/md_docs_2arduino.html)
    - For a Raspberry Pi
-      - An installer is provided: [Linux Installation](http://nRF24.github.io/RF24/md_docs_linux_install.html)
-        @see [General Linux/RPi setup and configuration page](http://nRF24.github.io/RF24/md_docs_rpi_general.html)
+      - An installer is provided: [Linux Installation](http://nRF24.github.io/RF24/md_docs_2linux__install.html)
+        @see [General Linux/RPi setup and configuration page](http://nRF24.github.io/RF24/md_docs_2rpi__general.html)
 3. Once testing is complete:
    - In Arduino IDE
       - File > Examples > RF24Mesh > RF24Mesh_Example
@@ -65,4 +65,4 @@ The @ref MESH_MAX_CHILDREN option restricts the maximum number of child nodes/no
 
 The MESH_NOMASTER macro optionally reduces program space and memory usage. Can be used on any node except for the master (nodeID 0)
 
-@see [General Usage](md_docs_general_usage.html) for information on how to work with the mesh once connected
+@see [General Usage](general_usage.md) for information on how to work with the mesh once connected