various improvments to docs (#193)

* improve doxygen CI

* RP2xxx CI use RF24 master branch

* amend image on main_page.md

* cross-ref to cppreferences.com

.github/workflows/build_rp2xxx.yml

@@ -59,7 +59,6 @@ jobs:
       with:
         repository: nRF24/RF24
         path: RF24
-        ref: rp2xxx
 
     - name: Install toolchain
       run: sudo apt update && sudo apt install gcc-arm-none-eabi libnewlib-arm-none-eabi build-essential

.github/workflows/doxygen.yml

@@ -40,11 +40,19 @@ jobs:
           touch doxygenAction
           echo "PROJECT_NUMBER = ${{ steps.latest_ver.outputs.release }}" >> doxygenAction
           echo "@INCLUDE = doxygenAction" >> Doxyfile
-      - name: build doxygen
-        uses: mattnotmitt/doxygen-action@v1
-        with:
-            working-directory: '.'
-            doxyfile-path: './Doxyfile'
+      - name: install Doxygen static libclang deps
+        run: sudo apt-get install libclang1-9 libclang-cpp9
+      - name: install doxygen from SF binary archives
+        env:
+          DOXYGEN_VERSION: '1.9.4'
+        run: |
+          mkdir doxygen && cd doxygen
+          curl -L https://sourceforge.net/projects/doxygen/files/rel-$DOXYGEN_VERSION/doxygen-$DOXYGEN_VERSION.linux.bin.tar.gz > doxygen.tar.gz
+          gunzip doxygen.tar.gz
+          tar xf doxygen.tar
+          cd doxygen-$DOXYGEN_VERSION
+          sudo make install
+      - run: doxygen
       - name: Save doxygen docs as artifact
         uses: actions/upload-artifact@v2
         with:

RF24Network.h

@@ -265,11 +265,10 @@ struct RF24NetworkHeader
      *
      * @note Now supports automatic fragmentation for very long messages, which can be sent as usual if fragmentation is enabled.
      *
-     * Fragmentation is enabled by default for all devices except ATTiny <br>
+     * Fragmentation is enabled by default for all devices except ATTiny.
      * Configure fragmentation and max payload size in RF24Network_config.h
      *
      * Use this constructor to create a header and then send a message
-     *
      * @code
      * uint16_t recipient_address = 011;
      *
@@ -299,7 +298,7 @@ struct RF24NetworkHeader
 /**
  * Frame structure for internal message handling, and for use by external applications
  *
- * The actual frame put over the air consists of a header (8-bytes) and a message payload (Up to 24-bytes)<br>
+ * The actual frame put over the air consists of a header (8-bytes) and a message payload (Up to 24-bytes).
  * When data is received, it is stored using the RF24NetworkFrame structure, which includes:
  * 1. The header containing information about routing the message and the message type
  * 2. The size of the included message
@@ -758,7 +757,7 @@ class RF24Network
      *
      * The `frag_ptr` is only used with Arduino (not RPi/Linux) and is mainly used for external data systems like RF24Ethernet. When
      * a payload of type @ref EXTERNAL_DATA_TYPE is received, and returned from update(), the `frag_ptr` will always point to the starting
-     * memory location of the received frame. <br>This is used by external data systems (RF24Ethernet) to immediately copy the received
+     * memory location of the received frame. This is used by external data systems (RF24Ethernet) to immediately copy the received
      * data to a buffer, without using the user-cache.
      *
      * @see RF24NetworkFrame
@@ -782,21 +781,21 @@ class RF24Network
      *
      * The following reserved/system message types are handled automatically, and not returned.
      *
-     * | System Message Types <br> (Not Returned) |
+     * | System Message Types (Not Returned) |
      * |-----------------------|
      * | @ref NETWORK_ADDR_RESPONSE |
      * | @ref NETWORK_ACK           |
      * | @ref NETWORK_PING          |
-     * | @ref NETWORK_POLL <br>(With multicast enabled) |
+     * | @ref NETWORK_POLL (With multicast enabled) |
      * | @ref NETWORK_REQ_ADDRESS   |
      */
     bool returnSysMsgs;
 
     /**
      * Network Flags allow control of data flow
      *
-     * Incoming Blocking: If the network user-cache is full, lets radio cache fill up. Radio ACKs are not sent when radio internal cache is full.<br>
-     * This behaviour may seem to result in more failed sends, but the payloads would have otherwise been dropped due to the cache being full.<br>
+     * Incoming Blocking: If the network user-cache is full, lets radio cache fill up. Radio ACKs are not sent when radio internal cache is full.
+     * This behaviour may seem to result in more failed sends, but the payloads would have otherwise been dropped due to the cache being full.
      *
      * | FLAGS | Value | Description |
      * |-------|-------|-------------|

docs/main_page.md

@@ -88,9 +88,7 @@ digit in the address represents a position in the tree further from the base.
   An example topology is shown below, with 5 nodes in direct communication with the master node,
   and multiple leaf nodes spread out at a distance, using intermediate nodes to reach other nodes.
 
-![
-  @image html example_tree.svg
-  ](https://github.com/nRF24/RF24Network/blob/CMake-4-Linux/images/example_tree.svg)
+@image html example_tree.svg
 
 ## How routing is handled
 

docs/sphinx/_static/custom_material.css

@@ -80,28 +80,19 @@ html .md-nav--primary .md-nav__title--site .md-nav__button {
 	margin-right: 0.5rem;
 }
 
-/* ************* temp workaround styling multi-line API signatures ******************* */
-/* In the future, we plan to do this without CSS in a more programatic way, but for now...  */
-
-.md-typeset dl.objdesc>dt.sig-wrap .n + .sig-paren::before,
-.md-typeset dl.api-field>dt.sig-wrap .n + .sig-paren::before {
-  content: "\a ";
-  white-space: pre;
-}
-
-.md-typeset dl.objdesc>dt.sig-wrap .sig-paren + .n:not(.sig-param)::before,
-.md-typeset dl.api-field>dt.sig-wrap .sig-paren + .n:not(.sig-param)::before,
-.md-typeset dl.objdesc>dt.sig-wrap .sig-param + .sig-param::before,
-.md-typeset dl.api-field>dt.sig-wrap .n.sig-param + .kt::before,
-.md-typeset dl.objdesc>dt.sig-wrap .n.sig-param + .kt::before,
-.md-typeset dl.api-field>dt.sig-wrap .n.sig-param + .n:not(.sig-param)::before,
-.md-typeset dl.objdesc>dt.sig-wrap .n.sig-param + .n:not(.sig-param)::before {
-  content: "\a     ";
-  white-space: break-spaces;
-}
-
-.md-typeset dl.api-field>dt.sig-wrap .sig-param:before,
-.md-typeset dl.objdesc>dt.sig-wrap .sig-param:before {
-  content: unset;
-  white-space: pre;
+/* 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/classRF24Network.rst

@@ -12,7 +12,13 @@ Basic API
 ============
 
 .. doxygenfunction:: RF24Network::begin (uint16_t _node_address)
+
+.. seealso:: :external:cpp:func:`RF24::begin()`
+
 .. doxygenfunction:: RF24Network::begin (uint8_t channel, uint16_t _node_address)
+
+.. seealso:: :external:cpp:func:`RF24::begin()`
+
 .. doxygenfunction:: RF24Network::update
 .. doxygenfunction:: RF24Network::available
 .. doxygenfunction:: RF24Network::read

docs/sphinx/conf.py

@@ -1,21 +1,24 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""Configuration file for the Sphinx documentation builder.
+
+This file only contains a selection of the most common options. For a full
+list see the documentation:
+https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""
+
+import subprocess
+import os
+import json
 
 # -- Path setup --------------------------------------------------------------
 
 # 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('.'))
-import subprocess
-import os
-import json
+
+# pylint: disable=invalid-name
 
 # -- Project information -----------------------------------------------------
 
@@ -46,6 +49,7 @@
     "sphinx_immaterial",
     "sphinx.ext.intersphinx",
     "sphinx.ext.autosectionlabel",
+    "sphinx_immaterial.cppreference",
 ]
 
 # auto-reference links (using intersphinx extension)
@@ -123,13 +127,15 @@
     "repo_url": "https://github.com/nRF24/RF24Network/",
     "repo_name": "RF24Network",
     "repo_type": "github",
-    # Visible levels of the global TOC; -1 means unlimited
-    "globaltoc_depth": 3,
     # If False, expand all TOC entries
     "globaltoc_collapse": False,
-    # If True, show hidden TOC entries
-    "globaltoc_includehidden": True,
 }
+
+object_description_options = [
+    ("cpp:functionParam", dict(include_in_toc=False, generate_synopses=None)),
+    ("cpp:function", dict(include_fields_in_toc=False)),
+]
+
 # Set link name generated in the top bar.
 html_title = "RF24Network C++ library"
 

docs/sphinx/examples/Arduino/Network_Ping_Sleep.rst

@@ -14,7 +14,7 @@ dropping network power consumption dramatically compared to previous capabilitie
 The displayed ``millis()`` count will give an indication of how much a node has been sleeping compared to the others, as ``millis()`` will
 not increment while a node sleeps.
 
-- Using this sketch, each node will send a ping to every other node in the network every few seconds.<br>
+- Using this sketch, each node will send a ping to every other node in the network every few seconds.
 - The RF24Network library will route the message across the mesh to the correct node.
 
 .. literalinclude:: ../../../../examples/Network_Ping_Sleep/Network_Ping_Sleep.ino