From ba5a2a571826452950c06a2281b722a0aa9c41b2 Mon Sep 17 00:00:00 2001
From: Brendan <2bndy5@gmail.com>
Date: Sat, 6 Apr 2024 00:51:45 -0700
Subject: [PATCH] minor doc updates (#225)
- upgrades to doxygen v1.10.0
- improved custom CSS
- added favicon
- fixed cross-links references
---
.github/workflows/doxygen.yml | 1 +
RF24Network.h | 6 +-
docs/Doxyfile | 15 +++--
docs/addressing.md | 4 +-
docs/doxygen-custom.css | 104 ++++++++++++++++++++++++++++++++++
docs/main_page.md | 8 +--
docs/tuning.md | 6 +-
7 files changed, 126 insertions(+), 18 deletions(-)
diff --git a/.github/workflows/doxygen.yml b/.github/workflows/doxygen.yml
index d4ff9b3a..c0f5af6b 100644
--- a/.github/workflows/doxygen.yml
+++ b/.github/workflows/doxygen.yml
@@ -32,4 +32,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/RF24Network.h b/RF24Network.h
index 38a2da19..b3687b0b 100644
--- a/RF24Network.h
+++ b/RF24Network.h
@@ -413,10 +413,10 @@ class ESBNetwork
/**
* Bring up the network using the current radio frequency/channel.
* Calling begin brings up the network, and configures the address, which designates the
- * location of the node within [RF24Network topology](md_docs_tuning.html).
+ * location of the node within [RF24Network topology](tuning.md).
*
* @note Node addresses are specified in Octal format, see
- * [RF24Network Addressing](md_docs_addressing.html) for more information. The address `04444`
+ * [RF24Network Addressing](addressing.md) for more information. The address `04444`
* is reserved for RF24Mesh usage (when a mesh node is connecting to the network).
* @warning Be sure to first call `RF24::begin()` to initialize the radio properly.
*
@@ -694,7 +694,7 @@ class ESBNetwork
/**
* Validate a network address as a proper logical address
* @note Addresses are specified in octal form, ie 011, 034.
- * Review [RF24Network addressing](md_docs_addressing.html) for more information.
+ * Review [RF24Network addressing](addressing.md) for more information.
* @param node The specified logical address of a network node.
* @return True if the specified `node` address is a valid network address, otherwise false.
* @remark This function will validate an improper address of `0100` as it is the reserved
diff --git a/docs/Doxyfile b/docs/Doxyfile
index ce5a7bd9..13368b1f 100644
--- 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
@@ -244,14 +246,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_SECTIONS tag is set to YES then the generated HTML
# documentation will contain sections that can be hidden and shown after the
diff --git a/docs/addressing.md b/docs/addressing.md
index 1ee56feb..30814363 100644
--- a/docs/addressing.md
+++ b/docs/addressing.md
@@ -13,7 +13,7 @@ Enhanced-Shock-Burst (ESB) functionality of the radios.
RF24Network uses a simple method of data compression to store the addresses using only 2 bytes, in a format designed to represent the
network topology in an intuitive way.
-See the [Topology and Overview](md_docs_tuning.html) page for more info regarding topology.
+See the [Topology and Overview](tuning.md) page for more info regarding topology.
## Decimal, Octal and Binary formats
@@ -67,4 +67,4 @@ printf("0%o\n", address);
@see
- [This cplusplus.com tutorial](http://www.cplusplus.com/doc/hex/) for more information number bases.
-- The [Topology and Overview page](md_docs_tuning.html) for more information regarding network topology.
+- The [Topology and Overview page](tuning.md) for more information regarding network topology.
diff --git a/docs/doxygen-custom.css b/docs/doxygen-custom.css
index 7d56191d..2b5ef5a1 100644
--- 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,');
+ --seealso-icon: url('data:image/svg+xml;utf8,');
+ --warning-icon: url('data:image/svg+xml;utf8,');
+ --remark-icon: url('data:image/svg+xml;utf8,');
+ --deprecated-icon: url('data:image/svg+xml;utf8,');
+}
+
+/* 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%);
+}
\ No newline at end of file
diff --git a/docs/main_page.md b/docs/main_page.md
index 9f4294a1..7edadb06 100644
--- a/docs/main_page.md
+++ b/docs/main_page.md
@@ -8,7 +8,7 @@ by the newly optimized [RF24 library fork](http://nRF24.github.com/RF24/) or usi
@see
[RF24 Library docs](http://nRF24.github.io/RF24/) for general RF24 configuration and setup.
- - [Linux Installation](http://nRF24.github.io/RF24/md_docs_linux_install.html) and [General Linux/RPi configuration and setup](http://nRF24.github.io/RF24/md_docs_rpi_general.html) documentation
+ - [Linux Installation](https://nrf24.github.io/RF24/md_docs_2linux__install.html) and [General Linux/RPi configuration and setup](https://nrf24.github.io/RF24/md_docs_2rpi__general.html) documentation
## Purpose/Goal
@@ -81,9 +81,9 @@ Please see the recent changes listed in [the github releases page](https://githu
## How to learn more
- [RF24Network Class Documentation](classRF24Network.html)
-- [Advanced Configuration Options](md_docs_advanced_config.html)
-- [Addressing format](md_docs_addressing.html)
-- [Topology and Overview](md_docs_tuning.html)
+- [Advanced Configuration Options](advanced_config.md)
+- [Addressing format](addressing.md)
+- [Topology and Overview](tuning.md)
- [Examples Page](examples.html). Start with `helloworld_*` examples.
### Additional Information & Add-ons
diff --git a/docs/tuning.md b/docs/tuning.md
index c3697d85..7b895309 100644
--- a/docs/tuning.md
+++ b/docs/tuning.md
@@ -58,7 +58,7 @@ Multicasting is also used by the RF24Mesh layer for dynamic addressing requests.
Routing of traffic is handled invisibly to the user, by the network layer. If the network addresses are
assigned in accordance with the physical layout of the network, nodes will route traffic automatically
-as required. Users simply constuct a header containing the appropriate destination address, and the network
+as required. Users simply construct a header containing the appropriate destination address, and the network
will forward it through to the correct node. Individual nodes only route individual fragments, so if using
fragmentation, routing nodes do not need it enabled, unless sending or receiving fragmented payloads themselves.
@@ -111,7 +111,7 @@ and adjusting the value of X from 1 to 15 (steps of 250us).
The core radio library also provides the ability to adjust the internal auto-retry count of the radio
modules. The default setting is 15 automatic retries per payload, and can be extended by configuring
the network.txTimeout variable. This default retry count should generally be left at 15, as per the
-example in the above section. An interval/retry setting of (15,15) will provide 15 retrys at intervals of
+example in the above section. An interval/retry setting of (15,15) will provide 15 retries at intervals of
4ms, taking up to 60ms per payload. The library now provides staggered timeout periods by default, but
they can also be adjusted on a per-node basis.
@@ -154,4 +154,4 @@ will not affect the operation greatly.
radio.setRetries(8, 15);
network.txTimeout = 553;
```
-3. First and third leaf nodes configured with default timeout periods or slightly increased timout periods.
+3. First and third leaf nodes configured with default timeout periods or slightly increased timeout periods.