Merge pull request #21 from adafruit/main

Pull 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
@@ -253,6 +260,7 @@ jobs:
         - "pca10100"
         - "pewpew10"
         - "pewpew_m4"
+        - "picoplanet"
         - "pirkey_m0"
         - "pitaya_go"
         - "pyb_nano_v2"

.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,6 @@
 [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

.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
@@ -84,6 +87,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 +110,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.
@@ -423,7 +445,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)

docs/autoapi/templates/python/module.rst

@@ -18,8 +18,7 @@
 {% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
 {% if visible_subpackages %}
 .. toctree::
-   :titlesonly:
-   :maxdepth: 3
+   :maxdepth: 2
 
 {% for subpackage in visible_subpackages %}
    {{ subpackage.short_name }}/index.rst

docs/requirements.txt

@@ -1,4 +1,4 @@
-sphinx<3
+sphinx<4
 recommonmark==0.6.0
 sphinxcontrib-svg2pdfconverter==0.1.0
 astroid

docs/rstjinja.py

@@ -6,18 +6,28 @@ def rstjinja(app, docname, source):
     Render our pages as a jinja template for fancy templating goodness.
     """
     # Make sure we're outputting HTML
-    if app.builder.format != 'html':
+    if app.builder.format not in ("html", "latex"):
         return
 
     # we only want our one jinja template to run through this func
     if "shared-bindings/support_matrix" not in docname:
         return
 
-    src = source[0]
+    src = rendered = source[0]
     print(docname)
-    rendered = app.builder.templates.render_string(
-        src, app.config.html_context
-    )
+
+    if app.builder.format == "html":
+        rendered = app.builder.templates.render_string(
+            src, app.config.html_context
+        )
+    else:
+        from sphinx.util.template import BaseRenderer
+        renderer = BaseRenderer()
+        rendered = renderer.render_string(
+            src,
+            app.config.html_context
+        )
+
     source[0] = rendered
 
 def setup(app):

extmod/moductypes.c

@@ -520,7 +520,7 @@ STATIC mp_obj_t uctypes_struct_subscr(mp_obj_t base_in, mp_obj_t index_in, mp_ob
             uint val_type = GET_TYPE(arr_sz, VAL_TYPE_BITS);
             arr_sz &= VALUE_MASK(VAL_TYPE_BITS);
             if (index >= arr_sz) {
-                nlr_raise(mp_obj_new_exception_msg(&mp_type_IndexError, translate("struct: index out of range")));
+                mp_raise_IndexError_varg(translate("%q index out of range"), MP_QSTR_struct);
             }
 
             if (t->len == 2) {

extmod/vfs_fat_file.c

@@ -42,7 +42,7 @@ const byte fresult_to_errno_table[20] = {
 
 STATIC void file_obj_print(const mp_print_t *print, mp_obj_t self_in, mp_print_kind_t kind) {
     (void)kind;
-    mp_printf(print, "<io.%s %p>", mp_obj_get_type_str(self_in), MP_OBJ_TO_PTR(self_in));
+    mp_printf(print, "<io.%q %p>", mp_obj_get_type_qstr(self_in), MP_OBJ_TO_PTR(self_in));
 }
 
 STATIC mp_uint_t file_obj_read(mp_obj_t self_in, void *buf, mp_uint_t size, int *errcode) {

extmod/vfs_posix_file.c

@@ -34,7 +34,7 @@ STATIC void check_fd_is_open(const mp_obj_vfs_posix_file_t *o) {
 STATIC void vfs_posix_file_print(const mp_print_t *print, mp_obj_t self_in, mp_print_kind_t kind) {
     (void)kind;
     mp_obj_vfs_posix_file_t *self = MP_OBJ_TO_PTR(self_in);
-    mp_printf(print, "<io.%s %d>", mp_obj_get_type_str(self_in), self->fd);
+    mp_printf(print, "<io.%q %d>", mp_obj_get_type_qstr(self_in), self->fd);
 }
 
 mp_obj_t mp_vfs_posix_file_open(const mp_obj_type_t *type, mp_obj_t file_in, mp_obj_t mode_in) {

frozen/Adafruit_CircuitPython_RFM9x

@@ -35,9 +35,9 @@
  * Table of constants for 2/pi, 396 Hex digits (476 decimal) of 2/pi
  */
 #ifdef __STDC__
-static const __int32_t two_over_pi[] = {
+static const __uint8_t two_over_pi[] = {
 #else
-static __int32_t two_over_pi[] = {
+static __uint8_t two_over_pi[] = {
 #endif
 0xA2, 0xF9, 0x83, 0x6E, 0x4E, 0x44, 0x15, 0x29, 0xFC,
 0x27, 0x57, 0xD1, 0xF5, 0x34, 0xDD, 0xC0, 0xDB, 0x62,
@@ -145,6 +145,7 @@ pio2_3t =  6.1232342629e-17; /* 0x248d3132 */
 		return -1;
 	    }
 	}
+#if CIRCUITPY_FULL_BUILD
 	if(ix<=0x43490f80) { /* |x| ~<= 2^7*(pi/2), medium size */
 	    t  = fabsf(x);
 	    n  = (__int32_t) (t*invpio2+half);
@@ -180,6 +181,11 @@ pio2_3t =  6.1232342629e-17; /* 0x248d3132 */
 	    if(hx<0) 	{y[0] = -y[0]; y[1] = -y[1]; return -n;}
 	    else	 return n;
 	}
+#else
+        // Suppress "defined but not used" diagnostics
+        (void) j; (void) fn; (void) r; (void) t; (void) w; (void) pio2_3t;
+        (void) pio2_3; (void) invpio2; (void)half; (void)npio2_hw;
+#endif
     /*
      * all other (large) arguments
      */

lib/libm/ef_rem_pio2.c

@@ -188,7 +188,7 @@ extern float __ieee754_scalbf __P((float,float));
 extern float __kernel_sinf __P((float,float,int));
 extern float __kernel_cosf __P((float,float));
 extern float __kernel_tanf __P((float,float,int));
-extern int   __kernel_rem_pio2f __P((float*,float*,int,int,int,const __int32_t*));
+extern int   __kernel_rem_pio2f __P((float*,float*,int,int,int,const __uint8_t*));
 
 /* A union which permits us to convert between a float and a 32 bit
    int.  */

lib/libm/fdlibm.h

@@ -62,10 +62,10 @@ two8   =  2.5600000000e+02, /* 0x43800000 */
 twon8  =  3.9062500000e-03; /* 0x3b800000 */
 
 #ifdef __STDC__
-	int __kernel_rem_pio2f(float *x, float *y, int e0, int nx, int prec, const __int32_t *ipio2)
+	int __kernel_rem_pio2f(float *x, float *y, int e0, int nx, int prec, const __uint8_t *ipio2)
 #else
 	int __kernel_rem_pio2f(x,y,e0,nx,prec,ipio2)
-	float x[], y[]; int e0,nx,prec; __int32_t ipio2[];
+	float x[], y[]; int e0,nx,prec; __uint8_t ipio2[];
 #endif
 {
 	__int32_t jz,jx,jv,jp,jk,carry,n,iq[20],i,j,k,m,q0,ih;