djsundog/circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #1985 from sommersoft/dynamic_support_matrix

Browse Source 
Docs: Dynamically Build Support Matrix Table
This commit is contained in:
Scott Shawcroft 2019-07-29 18:08:16 -07:00 committed by GitHub
commit f9d314b263
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 339 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.travis.yml
View File

@ -79,10 +79,10 @@ before_script:
# For coverage testing (upgrade is used to get latest urllib3 version)
- sudo apt-get install -y python3-pip
- pip3 install --user sh click
- pip3 install --user sh click setuptools
- ([[ -z "$TRAVIS_TESTS" ]] || sudo pip install --upgrade cpp-coveralls)
- (! var_search "${TRAVIS_TESTS-}" docs || sudo apt-get install -y librsvg2-bin)
- (! var_search "${TRAVIS_TESTS-}" docs || pip install --user Sphinx sphinx-rtd-theme recommonmark sphinxcontrib-svg2pdfconverter)
- (! var_search "${TRAVIS_TESTS-}" docs || pip3 install --user Sphinx sphinx-rtd-theme recommonmark sphinxcontrib-svg2pdfconverter)
- (! var_search "${TRAVIS_TESTS-}" translations || pip3 install --user polib)
# Check if there's any board missing in TRAVIS_BOARDS

20
conf.py
View File

@ -13,6 +13,7 @@
# All configuration values have a default; values that are commented out
# serve to show the default.
import json
import sys
import os
@ -24,8 +25,20 @@ from recommonmark.parser import CommonMarkParser
sys.path.insert(0, os.path.abspath('docs'))
sys.path.insert(0, os.path.abspath('.'))
import shared_bindings_matrix
master_doc = 'docs/index'
# Grab the JSON values to use while building the module support matrix
# in 'shared-bindings/index.rst'
#modules_support_matrix = shared_bindings_matrix.support_matrix_excluded_boards()
modules_support_matrix = shared_bindings_matrix.support_matrix_by_board()
html_context = {
'support_matrix': modules_support_matrix
}
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
@ -40,7 +53,9 @@ extensions = [
'sphinxcontrib.rsvgconverter',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage'
'sphinx.ext.coverage',
'rstjinja',
'c2rst'
]
# Add any paths that contain templates here, relative to this directory.
@ -49,8 +64,7 @@ templates_path = ['templates']
# The suffix of source filenames.
source_suffix = ['.rst', '.md', '.c', '.h']
source_parsers = {'.md': CommonMarkParser,
'.c': "c2rst.CStrip", '.h': "c2rst.CStrip"}
source_parsers = {'.md': CommonMarkParser}
# The encoding of source files.
#source_encoding = 'utf-8-sig'

46
docs/c2rst.py
View File

@ -1,19 +1,31 @@
import sphinx.parsers
def c2rst(app, docname, source):
""" Pre-parse '.c' & '.h' files that contain rST source.
"""
# Make sure we're outputting HTML
if app.builder.format != 'html':
return
class CStrip(sphinx.parsers.Parser):
def __init__(self):
self.rst_parser = sphinx.parsers.RSTParser()
fname = app.env.doc2path(docname)
if (not fname.endswith(".c") and
not fname.endswith(".h")):
#print("skipping:", fname)
return
def parse(self, inputstring, document):
# This setting is missing starting with Sphinx 1.7.1 so we set it ourself.
document.settings.tab_width = 4
document.settings.character_level_inline_markup = False
stripped = []
for line in inputstring.split("\n"):
line = line.strip()
if line == "//|":
stripped.append("")
elif line.startswith("//| "):
stripped.append(line[len("//| "):])
stripped = "\r\n".join(stripped)
self.rst_parser.parse(stripped, document)
src = source[0]
stripped = []
for line in src.split("\n"):
line = line.strip()
if line == "//|":
stripped.append("")
elif line.startswith("//| "):
stripped.append(line[len("//| "):])
stripped = "\r\n".join(stripped)
rendered = app.builder.templates.render_string(
stripped, app.config.html_context
)
source[0] = rendered
def setup(app):
app.connect("source-read", c2rst)

1
docs/library/network.rst
View File

@ -5,6 +5,7 @@
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: network
:noindex:
:synopsis: network configuration
This module provides network drivers and routing configuration. To use this

24
docs/rstjinja.py Normal file
View File

@ -0,0 +1,24 @@
# Derived from code on Eric Holscher's blog, found at:
# https://www.ericholscher.com/blog/2016/jul/25/integrating-jinja-rst-sphinx/
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':
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]
print(docname)
rendered = app.builder.templates.render_string(
src, app.config.html_context
)
source[0] = rendered
def setup(app):
app.connect("source-read", rstjinja)

244
docs/shared_bindings_matrix.py Normal file
View File

@ -0,0 +1,244 @@
# The MIT License (MIT)
#
# Copyright (c) 2019 Michael Schroeder
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.
#
import json
import os
import re
SUPPORTED_PORTS = ["atmel-samd", "nrf"]
def parse_port_config(contents, chip_keyword=None):
""" Compile a dictionary of port-wide module configs, which may
be categorized by chipset.
"""
chip_fam = "all"
ifeq_found = False
port_config_results = {"all": []}
chip_pattern = ""
if chip_keyword:
chip_pattern = (
re.compile("(?<=ifeq\s\(\$\({}\)\,)(\w+)".format(chip_keyword))
)
for line in contents:
if chip_keyword:
if not ifeq_found:
check_ifeq = chip_pattern.search(line)
if check_ifeq:
ifeq_found = True
chip_fam = check_ifeq.group(1)
#print("found chip:", chip_fam)
else:
ifeq_found = False
chip_fam = "all"
else:
if "endif" in line:
ifeq_found = False
chip_fam = "all"
if "CIRCUITPY_" in line:
if chip_fam in port_config_results:
port_config_results[chip_fam].append(line.rstrip("\n"))
else:
port_config_results[chip_fam] = [line.rstrip("\n")]
#print(port_config_results)
return port_config_results
def get_shared_bindings():
""" Get a list of modules in shared-bindings based on folder names
"""
return [item for item in os.listdir("./shared-bindings")]
def read_mpconfig():
""" Open 'circuitpy_mpconfig.mk' and return the contents.
"""
configs = []
with open("py/circuitpy_mpconfig.mk") as mpconfig:
configs = mpconfig.read()
return configs
def build_module_map():
""" Establish the base of the JSON file, based on the contents from
`configs`. Base will contain module names, if they're part of
the `FULL_BUILD`, or their default value (0 | 1).
"""
base = dict()
modules = get_shared_bindings()
configs = read_mpconfig()
full_build = False
for module in modules:
full_name = module
search_name = module.lstrip("_")
re_pattern = "CIRCUITPY_{}\s=\s(.+)".format(search_name.upper())
find_config = re.search(re_pattern, configs)
#print(module, "|", find_config)
if not find_config:
continue
full_build = int("FULL_BUILD" in find_config.group(0))
#print(find_config[1])
if not full_build:
default_val = find_config.group(1)
else:
default_val = "None"
base[search_name] = {
"name": full_name,
"full_build": str(full_build),
"default_value": default_val,
"excluded": {}
}
return base
def get_excluded_boards(base):
""" Cycles through each board's `mpconfigboard.mk` file to determine
if each module is included or not. Boards are selected by existence
in a port listed in `SUPPORTED_PORTS` (e.g. `/port/nrf/feather_52840`)
Boards are further categorized by their respective chipset (SAMD21,
SAMD51, nRF52840, etc.)
"""
modules = list(base.keys())
re_board_chip = None
chip_keyword = None
for port in SUPPORTED_PORTS:
# each port appears to use its own define for the chipset
if port in ["atmel-samd"]:
re_board_chip = re.compile("CHIP_FAMILY\s=\s(\w+)")
chip_keyword = "CHIP_FAMILY"
elif port in ["nrf"]:
re_board_chip = re.compile("MCU_VARIANT\s=\s(\w+)")
port_dir = "ports/{}".format(port)
port_config_contents = ""
with open(os.path.join(port_dir, "mpconfigport.mk")) as port_config:
port_config_contents = port_config.readlines()
port_config = parse_port_config(port_config_contents, chip_keyword)
for entry in os.scandir(os.path.join(port_dir, "boards")):
if not entry.is_dir():
continue
contents = ""
board_dir = os.path.join(entry.path, "mpconfigboard.mk")
with open(board_dir) as board:
contents = board.read()
board_chip = re_board_chip.search(contents)
#print(entry.name, board_chip.group(1))
if not board_chip:
board_chip = "Unknown Chip"
else:
board_chip = board_chip.group(1)
# add port_config results to contents
contents += "\n" + "\n".join(port_config["all"])
if board_chip in port_config:
contents += "\n" + "\n".join(port_config[board_chip])
for module in modules:
board_is_excluded = False
# check if board uses `SMALL_BUILD`. if yes, and current
# module is marked as `FULL_BUILD`, board is excluded
small_build = re.search("CIRCUITPY_SMALL_BUILD = 1", contents)
if small_build and base[module]["full_build"] == "1":
board_is_excluded = True
# check if module is specifically disabled for this board
re_pattern = "CIRCUITPY_{}\s=\s(\w)".format(module.upper())
find_module = re.search(re_pattern, contents)
if not find_module:
# check if default inclusion is off ('0'). if the board doesn't
# have it explicitly enabled, its excluded.
if base[module]["default_value"] == "0":
board_is_excluded = True
else:
if (find_module.group(1) == "0" and
find_module.group(1) != base[module]["default_value"]):
board_is_excluded = True
if board_is_excluded:
if board_chip in base[module]["excluded"]:
base[module]["excluded"][board_chip].append(entry.name)
else:
base[module]["excluded"][board_chip] = [entry.name]
#print(json.dumps(base, indent=2))
return base
def support_matrix_excluded_boards():
""" Compiles a list of available modules, and which board definitions
do not include them.
"""
base = build_module_map()
return get_excluded_boards(base)
def support_matrix_by_board():
""" Compiles a list of the available core modules available for each
board.
"""
base = build_module_map()
base_with_exclusions = get_excluded_boards(base)
boards = dict()
for port in SUPPORTED_PORTS:
port_dir = "ports/{}/boards".format(port)
for entry in os.scandir(port_dir):
if not entry.is_dir():
continue
board_modules = []
board_name = entry.name
board_contents = ""
with open(os.path.join(entry.path, "mpconfigboard.h")) as get_name:
board_contents = get_name.read()
board_name_re = re.search("(?<=MICROPY_HW_BOARD_NAME)\s+(.+)",
board_contents)
if board_name_re:
board_name = board_name_re.group(1).strip('"')
for module in base_with_exclusions.keys():
#print(module)
board_has_module = True
if base_with_exclusions[module]["excluded"]:
for port in base_with_exclusions[module]["excluded"].values():
#print(port)
if entry.name in port:
board_has_module = False
if board_has_module:
board_modules.append(base_with_exclusions[module]["name"])
boards[board_name] = sorted(board_modules)
#print(json.dumps(boards, indent=2))
return boards

62
shared-bindings/index.rst
View File

@ -1,11 +1,11 @@
Core Modules
========================================
These core modules are intended on being consistent across ports. Currently
they are only implemented in the SAMD21 and ESP8266 ports. A module may not exist
in a port if no underlying hardware support is present or if flash space is
limited. For example, a microcontroller without analog features will not have
`analogio`.
These core modules are intended on being consistent across ports and boards.
A module may not exist on a port/board if no underlying hardware support is
present or if flash space is limited. For example, a microcontroller without
analog features will not have `analogio`. See the `support_matrix` page for
a list of modules supported on each board.
Modules
---------
@ -14,56 +14,6 @@ Modules
:glob:
:maxdepth: 3
support_matrix
*/__init__
help
.. _module-support-matrix:
Support Matrix
---------------
NOTE 1: **All Supported** means the following ports are supported: SAMD21, SAMD21 Express,
SAMD51, SAMD51 Express, and ESP8266.
NOTE 2: **SAMD** and/or **SAMD Express** without additional numbers, means both SAMD21 & SAMD51 versions
are supported.
NOTE 3: The `pIRkey SAMD21 board <https://www.adafruit.com/product/3364>`_ is specialized and may not
have modules as listed below.
================= ==============================
Module Supported Ports
================= ==============================
`analogio` **All Supported**
`audiobusio` **SAMD/SAMD Express**
`audioio` **SAMD Express**
`audiocore` **All with audioio**
`binascii` **ESP8266**
`bitbangio` **SAMD Express, ESP8266**
`board` **All Supported**
`bleio` **nRF**
`busio` **All Supported**
`digitalio` **All Supported**
`frequencyio` **SAMD51**
`gamepad` **SAMD Express, nRF**
`hashlib` **ESP8266**
`i2cslave` **SAMD Express**
`math` **All Supported**
`microcontroller` **All Supported**
`multiterminal` **ESP8266**
`neopixel_write` **All Supported**
`nvm` **SAMD Express**
`os` **All Supported**
`pulseio` **SAMD/SAMD Express**
`ps2io` **SAMD/SAMD Express**
`random` **All Supported**
`rotaryio` **SAMD51, SAMD Express**
`storage` **All Supported**
`struct` **All Supported**
`supervisor` **SAMD/SAMD Express**
`time` **All Supported**
`touchio` **SAMD/SAMD Express**
`uheap` **Debug (All)**
`usb_hid` **SAMD/SAMD Express**
`_pixelbuf` **SAMD Express**
`_stage` **SAMD/SAMD Express**
================= ==============================

16
shared-bindings/support_matrix.rst Normal file
View File

@ -0,0 +1,16 @@
.. _module-support-matrix:
Support Matrix
===============
The following table lists the available built-in modules for each CircuitPython
capable board.
.. csv-table::
:header-rows: 1
:widths: 7, 50
"Board", "Modules Available"
{% for key, value in support_matrix|dictsort -%}
"{{ key }}", "{{ '`' ~ value|join("`, `") ~ '`' }}"
{% endfor -%}