update submodules and docs (#17)

* update submodules and docs

Yet another regular maintenance update. The  changes include:
- update RF24 to v1.4.7
- update RF24Network to v2.0.0
- update RF24Mesh to v2.0.0
- update pybind11 to v2.10.4
- fix .gitattributes file messing with png files
- fix pylint deprecation warnings about old config settings

Updates to the docs include necessary changes to the docs' conf.py and adding social media cards to the metadata for each page. The social media cards are generated per the newly added layout.yml file/spec (included in these changes).

Author: 2bndy5

.gitattributes

@@ -10,7 +10,6 @@
 *.txt text eol=lf
 *.css text eol=lf
 *.svg text eol=lf
-*.png text eol=lf
 *.sh text eol=lf
 *.yml text eol=lf
 *.bat text eol=crlf

.gitignore

@@ -69,6 +69,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/social_cards_cache/
 
 # PyBuilder
 target/

.pylintrc

@@ -558,5 +558,5 @@ preferred-modules=
 
 # Exceptions that will emit a warning when being caught. Defaults to
 # "BaseException, Exception".
-overgeneral-exceptions=BaseException,
-                       Exception
+overgeneral-exceptions=builtins.BaseException,
+                       builtins.Exception

RF24

@@ -1,3 +1,5 @@
+:description: How to use the radio as a fake Bluetooth Low Energy Beacon.
+
 BLE API
 =================
 

RF24Mesh

@@ -6,17 +6,19 @@
 https://www.sphinx-doc.org/en/master/usage/configuration.html
 """
 # pylint: disable=invalid-name
+import os
+
 try:
     from importlib.metadata import version as get_version
 except ImportError:  # for python v3.7 or older
     from importlib_metadata import version as get_version  # type: ignore
 
 # -- Project information -----------------------------------------------------
 
-project = "pyrf24"
-copyright = "2020, TMRh20 Avamander 2bndy5"  # pylint: disable=redefined-builtin
+project = "pyRF24"
+copyright = "2023, TMRh20 Avamander 2bndy5"  # pylint: disable=redefined-builtin
 author = "TMRh20 Avamander 2bndy5"
-language="en"
+language = "en"
 
 # The full version, including alpha/beta/rc tags
 release = get_version("pyrf24")
@@ -31,7 +33,8 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx_immaterial",
-    "sphinx.ext.graphviz",
+    "sphinx_immaterial.graphviz",
+    "sphinx_social_cards",
 ]
 
 intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
@@ -52,6 +55,32 @@
 default_role = "any"
 
 
+# -- Options for sphinx_social_cards -------------------------------------------------
+social_cards = {
+    "site_url": os.environ.get(
+        "READTHEDOCS_CANONICAL_URL", "https://nrf24.github.io/pyRF24/"
+    ),
+    "description": (
+        "A python package that wraps the RF24, RF24Network, and RF24Mesh C++ libraries."
+    ),
+    "image_paths": ["social_cards/images"],
+    "cards_layout_dir": ["social_cards/layouts"],
+    "cards_layout": "custom",
+    "cards_layout_options": {
+        "logo": {
+            "image": "material/access-point",
+            "color": "lime",
+        },
+        "background_color": "#2c2c2c",
+        "background_image": "logo_large_no-bg.png",
+        "color": "lime",
+    },
+    # "debug": {
+    #     "enable": True,
+    #     "color": "lime",
+    # },
+}
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -96,7 +125,6 @@
     # Set the repo location to get a badge with stats
     "repo_url": "https://github.com/nRF24/pyRF24/",
     "repo_name": "pyRF24",
-    "repo_type": "github",
     # If False, expand all TOC entries
     "globaltoc_collapse": False,
 }
@@ -138,7 +166,7 @@
     },
     {
         "name": "important",
-        "icon": "material/school",
+        "icon": "material/alert-decagram",
         "override": True,
     },
 ]

RF24Network

@@ -23,9 +23,3 @@
    :hidden:
 
    topology
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`

docs/ble_api.rst

@@ -1,2 +1,3 @@
 sphinx<6.0
 sphinx-immaterial
+sphinx-social-cards

docs/conf.py

@@ -1,3 +1,5 @@
+:description: How to use the radio's basic functionality.
+
 RF24 API
 ========
 

docs/index.rst

@@ -1,3 +1,5 @@
+:description: How to use the radio as a dynamic mesh network node.
+
 RF24Mesh API
 ============
 

docs/requirements.txt

@@ -1,3 +1,5 @@
+:description: How to use the radio as a static network node.
+
 RF24Network API
 ===============
 

docs/rf24_api.rst

@@ -0,0 +1,87 @@
+# {% block color_vals %}
+bg_color: &bg_color '{{ layout.background_color }}'
+fg_color: &fg_color '{{ layout.color }}'
+# {% endblock %}
+
+row1_width: &row1_width 1080
+row2_width: &row2_width 500
+col2: &col2 310
+
+layers:
+  # the base layer for the background
+  - background:
+      color: *bg_color
+      image: >
+        {% if layout.background_image %}
+        {{ layout.background_image }}
+        {% endif %}
+  # the layer for the logo/icon image
+  - size: { width: 60, height: 60 }
+    offset: { x: 1050, y: 60 }
+    icon:
+      image: >
+        {% if page.meta.icon %}
+        {{ page.meta.icon }}
+        {% elif layout.logo.image %}
+        {{ layout.logo.image }}
+        {% endif %}
+      color: >
+        {% if layout.logo.color %}
+        {{ layout.logo.color }}
+        {% endif %}
+  # the layer for the large logo image
+  - size: { width: 640, height: 320 }
+    offset: { x: 560, y: *col2 }
+    icon:
+      image: '{{ layout.background_image }}'
+  # fancy bg art
+  # {% for r in range(60, 640, 90) %}
+  - offset: { x: {{ -r }}, y: {{ -r }} }
+    size: { width: {{ r  * 2}}, height: {{ r * 2 }} }
+    ellipse:
+      border:
+        width: {{ ((640 - r) * 0.1) | int }}
+        color: '#802a033c'
+  # {% endfor %}
+  # the layer for the site's name
+  - offset: { x: 60, y: 60 }
+    size: { width: 960, height: 60 }
+    typography:
+      content: '{{ config.docstitle }}'
+      align: end center
+      color: '{{ layout.color }}'
+  # the layer for the page's title
+  - size: { width: *row1_width, height: 150 }
+    offset: { x: 60, y: 150 }
+    typography:
+      content: >
+        {% if page.meta.title %}
+        {{ page.meta.title }}
+        {% elif page.title %}
+        {{ page.title }}
+        {% endif %}
+      line:
+        height: 0.9
+      font:
+        weight: 500
+      border: 
+        color: deep-orange
+        width: 4
+      color: *fg_color
+      align: center top
+  # the layer for the site's (or page's) description
+  - offset: { x: 60, y: *col2 }
+    size: { width: 490, height: 290 }
+    typography:
+      content: >
+        {% if page.meta and page.meta.description %}
+        {{ page.meta.description }}
+        {% else %}
+        {{ config.site_description }}
+        {% endif %}
+      line:
+        height: 0.87
+        amount: 4
+      overflow: on
+      align: start bottom
+      color: '{{ layout.color }}'

docs/rf24_mesh_api.rst

@@ -1,3 +1,5 @@
+:description: How a network is constructed, address composition, and common points of failure during Mesh connecting.
+
 Network Topology
 ================
 
@@ -20,29 +22,27 @@ integers and use an octal counting scheme.
 .. graphviz::
 
     graph network_hierarchy {
-        bgcolor="#323232A1"
         newrank=true
         // ratio="0.65"
         node [
             fontcolor="#FEFEFE"
             fontsize=14
-            fontname=Arial
         ]
         pad="0"
         margin="0"
         subgraph cluster_hierarchy {
-            bgcolor="#24242400"
             color="#24242400"
             node [
+                fontcolor="#FEFEFE"
                 style=filled
-                color="#FEFEFE7f"
+                color="var(--md-graphviz-edge-color)"
             ]
-            edge [color="#FEFEFE" style="setlinewidth(2)"]
+            edge [style="setlinewidth(2)"]
             subgraph lvl_0 {
                 "0o0" [
                     shape="circle"
                     style="radial"
-                    fillcolor="0.85:#018268;0:#000"
+                    fillcolor="#000000;0.85:#018268"
                 ]
             }
             subgraph lvl_1 {
@@ -68,10 +68,7 @@ integers and use an octal counting scheme.
             "0o324" -- "0o2324"; "0o324" -- "0o3324"; "0o324" -- "0o4324"; "0o324" -- "0o5324"
         }
         subgraph cluster_legend {
-            bgcolor="#242424"
-            color="#24242400"
             "Legend" [
-                color="#FEF9A9"
                 shape=plain
                 margin=0
                 label=<
@@ -81,7 +78,7 @@ integers and use an octal counting scheme.
                             </TR>
                             <TR>
                                 <TD>Network Level 0</TD>
-                                <TD BORDER="1" STYLE="rounded,radial" BGCOLOR="#000:#018268">        </TD>
+                                <TD BORDER="1" STYLE="rounded,radial" BGCOLOR="#000000:#018268">        </TD>
                             </TR>
                             <TR>
                                 <TD>Network Level 1</TD>
@@ -108,6 +105,7 @@ integers and use an octal counting scheme.
         }
     }
 
+
 Hopefully, you should see the pattern. There can be up to a maximum of 5 network levels (that's
 0-4 ordered from lowest to highest).
 
@@ -128,40 +126,57 @@ graph only demonstrates
 
     graph network_levels {
         layout=twopi
-        bgcolor="#323232A1"
         ratio="0.825"
-        node [
-            style=filled
-            fontcolor="#FEFEFE"
-            color="#FEFEFE7f"
-            fontsize=14
-            fontname=Arial
-        ]
-        edge [color="#FEFEFE" style="setlinewidth(2)"]
+        edge [style="setlinewidth(2)"]
         ranksep="0.85:0.9:0.95:1.1"
         subgraph lvl_0 {
+            node [
+                color="var(--md-graphviz-edge-color)"
+                fontcolor="#FEFEFE"
+                fontsize=14
+            ]
             "0o0" [
                 root=true
                 shape="circle"
                 style="radial"
-                fillcolor="0.9:#018268;0:#000"
+                fillcolor="#000000;0.9:#018268"
             ]
         }
         subgraph lvl_1 {
-            node [fillcolor="#3E0180"]
+            node [
+                fillcolor="#3E0180"
+                color="var(--md-graphviz-edge-color)"
+                fontcolor="#FEFEFE"
+                fontsize=14
+            ]
             "0o1" "0o2" "0o3" "0o4" "0o5"
         }
         subgraph lvl_2 {
-            node [fillcolor="#014B80"]
+            node [
+                fillcolor="#014B80"
+                color="var(--md-graphviz-edge-color)"
+                fontcolor="#FEFEFE"
+                fontsize=14
+            ]
             "0o11" "0o21" "0o12" "0o22" "0o13" "0o23" "0o14" "0o24" "0o15" "0o25"
         }
         subgraph lvl_3 {
-            node [fillcolor="#0E6902"]
+            node [
+                fillcolor="#0E6902"
+                color="var(--md-graphviz-edge-color)"
+                fontcolor="#FEFEFE"
+                fontsize=14
+            ]
             "0o311" "0o411" "0o321" "0o421" "0o312" "0o412" "0o322" "0o422" "0o313" "0o413"
             "0o323" "0o423" "0o314" "0o414" "0o324" "0o424" "0o315" "0o415" "0o325" "0o425"
         }
         subgraph lvl_4 {
-            node [fillcolor="#80010B"]
+            node [
+                fillcolor="#80010B"
+                color="var(--md-graphviz-edge-color)"
+                fontcolor="#FEFEFE"
+                fontsize=14
+            ]
             "0o5311" "0o5411" "0o5321" "0o5312" "0o5421" "0o5313" "0o5314" "0o5315" "0o5322"
             "0o5323" "0o5324" "0o5325" "0o5412" "0o5423" "0o5422" "0o5413" "0o5414" "0o5424"
             "0o5415" "0o5425"