Merge pull request #28 from adafruit/main

Merge from adafruit/main

Author: DavePutz

.github/workflows/build.yml

@@ -36,7 +36,7 @@ jobs:
     - name: Install deps
       run: |
         sudo apt-get install -y eatmydata
-        sudo eatmydata apt-get install -y gettext librsvg2-bin mingw-w64
+        sudo eatmydata apt-get install -y gettext librsvg2-bin mingw-w64 latexmk texlive-fonts-recommended texlive-latex-recommended texlive-latex-extra
         pip install requests sh click setuptools cpp-coveralls "Sphinx<4" sphinx-rtd-theme recommonmark sphinx-autoapi sphinxcontrib-svg2pdfconverter polib pyyaml astroid isort black awscli
     - name: Versions
       run: |
@@ -73,12 +73,19 @@ jobs:
       with:
         name: stubs
         path: circuitpython-stubs*
-    - name: Docs
+    - name: Test Documentation Build (HTML)
       run: sphinx-build -E -W -b html -D version=${{ env.CP_VERSION }} -D release=${{ env.CP_VERSION }} . _build/html
     - uses: actions/upload-artifact@v2
       with:
         name: docs
         path: _build/html
+    - name: Test Documentation Build (LaTeX/PDF)
+      run: |
+        make latexpdf
+    - uses: actions/upload-artifact@v2
+      with:
+        name: docs
+        path: _build/latex
     - name: Translations
       run: make check-translate
     - name: New boards check
@@ -227,6 +234,7 @@ jobs:
         - "makerdiary_nrf52840_m2_devkit"
         - "makerdiary_nrf52840_mdk"
         - "makerdiary_nrf52840_mdk_usb_dongle"
+        - "matrixportal_m4"
         - "meowbit_v121"
         - "meowmeow"
         - "metro_m0_express"
@@ -253,6 +261,7 @@ jobs:
         - "pca10100"
         - "pewpew10"
         - "pewpew_m4"
+        - "picoplanet"
         - "pirkey_m0"
         - "pitaya_go"
         - "pyb_nano_v2"
@@ -266,6 +275,7 @@ jobs:
         - "pyportal"
         - "pyportal_titano"
         - "pyruler"
+        - "qtpy_m0"
         - "raytac_mdbt50q-db-40"
         - "robohatmm1_m4"
         - "sam32"
@@ -400,8 +410,11 @@ jobs:
       fail-fast: false
       matrix:
         board:
+        - "electroniccats_bastwifi"
+        - "espressif_kaluga_1"
         - "espressif_saola_1_wroom"
         - "espressif_saola_1_wrover"
+        - "microdev_micro_s2"
         - "unexpectedmaker_feathers2"
 
     steps:
@@ -422,6 +435,11 @@ jobs:
       with:
         path: ${{ github.workspace }}/.idf_tools
         key: ${{ runner.os }}-idf-tools-${{ hashFiles('.git/modules/ports/esp32s2/esp-idf/HEAD') }}-20200801
+    - name: Clone IDF submodules
+      run: |
+        (cd $IDF_PATH && git submodule update --init)
+      env:
+        IDF_PATH: ${{ github.workspace }}/ports/esp32s2/esp-idf
     - name: Install IDF tools
       run: |
         $IDF_PATH/tools/idf_tools.py --non-interactive install required

.gitignore

@@ -57,7 +57,7 @@ _build
 ######################
 genrst/
 /autoapi/
-/shared-bindings/**/*.rst
+/shared-bindings/*/**/*.rst
 
 # ctags and similar
 ###################
@@ -80,3 +80,8 @@ TAGS
 *.mo
 
 .vscode
+
+# Python Virtual Environments
+####################
+.venv
+.env

.gitmodules

@@ -147,3 +147,9 @@
 [submodule "ports/esp32s2/esp-idf"]
 	path = ports/esp32s2/esp-idf
 	url = https://github.com/tannewt/esp-idf.git
+[submodule "frozen/Adafruit_CircuitPython_RFM9x"]
+	path = frozen/Adafruit_CircuitPython_RFM9x
+	url = https://github.com/adafruit/Adafruit_CircuitPython_RFM9x.git
+[submodule "frozen/Adafruit_CircuitPython_RFM69"]
+	path = frozen/Adafruit_CircuitPython_RFM69
+	url = https://github.com/adafruit/Adafruit_CircuitPython_RFM69.git

.readthedocs.yml

@@ -8,6 +8,13 @@
 
 version: 2
 
+submodules:
+    include:
+        - extmod/ulab
+
+formats:
+  - pdf
+
 python:
     version: 3
     install:

Makefile

@@ -245,6 +245,10 @@ stubs:
 	@$(PYTHON) tools/extract_pyi.py ports/atmel-samd/bindings $(STUBDIR)
 	@$(PYTHON) setup.py -q sdist
 
+.PHONY: check-stubs
+check-stubs: stubs
+	MYPYPATH=$(STUBDIR) mypy --strict $(STUBDIR)
+
 update-frozen-libraries:
 	@echo "Updating all frozen libraries to latest tagged version."
 	cd frozen; for library in *; do cd $$library; ../../tools/git-checkout-latest-tag.sh; cd ..; done

conf.py

@@ -17,14 +17,17 @@
 #
 # SPDX-License-Identifier: MIT
 
-import json
 import logging
 import os
+import re
 import subprocess
 import sys
 import urllib.parse
 
 import recommonmark
+from sphinx.transforms import SphinxTransform
+from docutils import nodes
+from sphinx import addnodes
 
 # 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
@@ -39,6 +42,9 @@
 # Grab the JSON values to use while building the module support matrix
 # in 'shared-bindings/index.rst'
 
+# The stubs must be built before we calculate the shared bindings matrix
+subprocess.check_output(["make", "stubs"])
+
 #modules_support_matrix = shared_bindings_matrix.support_matrix_excluded_boards()
 modules_support_matrix = shared_bindings_matrix.support_matrix_by_board()
 
@@ -74,7 +80,6 @@
     '.md': 'markdown',
 }
 
-subprocess.check_output(["make", "stubs"])
 extensions.append('autoapi.extension')
 
 autoapi_type = 'python'
@@ -84,6 +89,7 @@
 autoapi_add_toctree_entry = False
 autoapi_options = ['members', 'undoc-members', 'private-members', 'show-inheritance', 'special-members', 'show-module-summary']
 autoapi_template_dir = 'docs/autoapi/templates'
+autoapi_python_class_content = "both"
 autoapi_python_use_implicit_namespaces = True
 autoapi_root = "shared-bindings"
 
@@ -106,7 +112,25 @@
 #
 # We don't follow "The short X.Y version" vs "The full version, including alpha/beta/rc tags"
 # breakdown, so use the same version identifier for both to avoid confusion.
-version = release = '0.0.0'
+
+final_version = ""
+git_describe = subprocess.run(
+    ["git", "describe", "--dirty", "--tags"],
+    stdout=subprocess.PIPE,
+    stderr=subprocess.STDOUT,
+    encoding="utf-8"
+)
+if git_describe.returncode == 0:
+    git_version = re.search(
+        r"^\d(?:\.\d){0,2}(?:\-(?:alpha|beta|rc)\.\d+){0,1}",
+        str(git_describe.stdout)
+    )
+    if git_version:
+        final_version = git_version[0]
+else:
+    print("Failed to retrieve git version:", git_describe.stdout)
+
+version = release = final_version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -122,6 +146,7 @@
 # directories to ignore when looking for source files.
 exclude_patterns = ["**/build*",
                     ".git",
+                    ".env",
                     ".venv",
                     ".direnv",
                     "docs/autoapi",
@@ -423,7 +448,38 @@ def generate_redirects(app):
             with open(redirected_filename, 'w') as f:
                 f.write(TEMPLATE % urllib.parse.quote(to_path, '#/'))
 
+
+class CoreModuleTransform(SphinxTransform):
+    default_priority = 870
+
+    def _convert_first_paragraph_into_title(self):
+        title = self.document.next_node(nodes.title)
+        paragraph = self.document.next_node(nodes.paragraph)
+        if not title or not paragraph:
+            return
+        if isinstance(paragraph[0], nodes.paragraph):
+            paragraph = paragraph[0]
+        if all(isinstance(child, nodes.Text) for child in paragraph.children):
+            for child in paragraph.children:
+                title.append(nodes.Text(" \u2013 "))
+                title.append(child)
+            paragraph.parent.remove(paragraph)
+
+    def _enable_linking_to_nonclass_targets(self):
+        for desc in self.document.traverse(addnodes.desc):
+            for xref in desc.traverse(addnodes.pending_xref):
+                if xref.attributes.get("reftype") == "class":
+                    xref.attributes.pop("refspecific", None)
+
+    def apply(self, **kwargs):
+        docname = self.env.docname
+        if docname.startswith(autoapi_root) and docname.endswith("/index"):
+            self._convert_first_paragraph_into_title()
+            self._enable_linking_to_nonclass_targets()
+
+
 def setup(app):
     app.add_css_file("customstyle.css")
     app.add_config_value('redirects_file', 'redirects', 'env')
     app.connect('builder-inited', generate_redirects)
+    app.add_transform(CoreModuleTransform)