update submodules and docs

.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

docs/ble_api.rst

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

docs/conf.py

@@ -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,
  },
 ]

docs/index.rst

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

docs/requirements.txt

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

docs/rf24_api.rst

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

docs/rf24_mesh_api.rst

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

docs/rf24_network_api.rst

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

docs/social_cards/layouts/custom.yml

@@ -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/topology.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"