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

Documentation rework to unify the docs together rather than having them

Browse Source 
on a per port basis.

Also enables generating docs from inline RST in C code. Simply omits all
lines except those that start with //|. Indentation after "//| " will be
preserved.
This commit is contained in:
Scott Shawcroft 2016-10-18 17:42:47 -07:00
parent cb99ae5032
commit 46e7f8e4fb
26 changed files with 183 additions and 746 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored
View File

@ -39,3 +39,7 @@ __pycache__/
###################### ######################
GNUmakefile GNUmakefile
user.props user.props
# Sphinx output
###############
_build

17
c2rst.py Normal file
View File

@ -0,0 +1,17 @@
import sphinx.parsers
import docutils.parsers.rst as rst
class CStrip(sphinx.parsers.Parser):
def __init__(self):
self.rst_parser = rst.Parser()
def parse(self, inputstring, document):
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)

76
docs/conf.py → conf.py Executable file → Normal file
View File

@ -21,46 +21,14 @@ import os
# documentation root, use os.path.abspath to make it absolute, like shown here. # documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('.')) sys.path.insert(0, os.path.abspath('.'))
# Work out the port to generate the docs for
from collections import OrderedDict
micropy_port = os.getenv('MICROPY_PORT') or 'pyboard'
tags.add('port_' + micropy_port)
ports = OrderedDict((
('unix', 'unix'),
('pyboard', 'the pyboard'),
('wipy', 'the WiPy'),
('esp8266', 'the ESP8266'),
))
# The members of the html_context dict are available inside topindex.html
micropy_version = os.getenv('MICROPY_VERSION') or 'latest'
micropy_all_versions = (os.getenv('MICROPY_ALL_VERSIONS') or 'latest').split(',')
url_pattern = '%s/en/%%s/%%s' % (os.getenv('MICROPY_URL_PREFIX') or '/',)
html_context = {
'port':micropy_port,
'port_name':ports[micropy_port],
'port_version':micropy_version,
'all_ports':[
(port_id, url_pattern % (micropy_version, port_id))
for port_id, port_name in ports.items()
],
'all_versions':[
(ver, url_pattern % (ver, micropy_port))
for ver in micropy_all_versions
],
'downloads':[
('PDF', url_pattern % (micropy_version, 'micropython-%s.pdf' % micropy_port)),
],
}
# Specify a custom master document based on the port name # Specify a custom master document based on the port name
master_doc = micropy_port + '_' + 'index' master_doc = 'index'
# -- General configuration ------------------------------------------------ # -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here. # If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0' needs_sphinx = '1.3'
# Add any Sphinx extension module names here, as strings. They can be # Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@ -70,17 +38,16 @@ extensions = [
'sphinx.ext.doctest', 'sphinx.ext.doctest',
'sphinx.ext.intersphinx', 'sphinx.ext.intersphinx',
'sphinx.ext.todo', 'sphinx.ext.todo',
'sphinx.ext.coverage', 'sphinx.ext.coverage'
'sphinx_selective_exclude.modindex_exclude',
'sphinx_selective_exclude.eager_only',
'sphinx_selective_exclude.search_auto_exclude',
] ]
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path = ['templates'] templates_path = ['templates']
# The suffix of source filenames. # The suffix of source filenames.
source_suffix = '.rst' source_suffix = ['.rst', '.md', '.c', '.h']
source_parsers = {'.c': "c2rst.CStrip", '.h': "c2rst.CStrip"}
# The encoding of source files. # The encoding of source files.
#source_encoding = 'utf-8-sig' #source_encoding = 'utf-8-sig'
@ -89,8 +56,8 @@ source_suffix = '.rst'
#master_doc = 'index' #master_doc = 'index'
# General information about the project. # General information about the project.
project = 'MicroPython' project = 'Adafruit\'s MicroPython'
copyright = '2014-2016, Damien P. George and contributors' copyright = '2014-2016, Damien P. George, Scott Shawcroft, Tony DiCola and other contributors'
# The version info for the project you're documenting, acts as replacement for # The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the # |version| and |release|, also used in various other places throughout the
@ -113,7 +80,7 @@ release = '1.8.4'
# List of patterns, relative to source directory, that match files and # List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files. # directories to ignore when looking for source files.
exclude_patterns = ['build'] exclude_patterns = ["*/build-*", "atmel-samd/asf", "atmel-samd/**.c", "atmel-samd/**.h", "bare-arm", "cc3200", "cc3200/FreeRTOS", "cc3200/hal", "drivers", "esp8266", "examples", "extmod", "lib", "minimal", "mpy-cross", "pic16bit", "py", "qemu-arm", "stmhal", "stmhal/hal", "stmhal/cmsis", "stmhal/usbdev", "stmhal/usbhost", "teensy", "tests", "tools", "unix", "windows", "zephyr"]
# The reST default role (used for this markup: `text`) to use for all # The reST default role (used for this markup: `text`) to use for all
# documents. # documents.
@ -183,7 +150,7 @@ else:
# Add any paths that contain custom static files (such as style sheets) here, # Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files, # relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css". # so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['static'] html_static_path = ['docs/static']
# Add any extra paths that contain custom files (such as robots.txt or # Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied # .htaccess) here, relative to this directory. These files are copied
@ -203,7 +170,7 @@ html_last_updated_fmt = '%d %b %Y'
# Additional templates that should be rendered to pages, maps page names to # Additional templates that should be rendered to pages, maps page names to
# template names. # template names.
html_additional_pages = {"index": "topindex.html"} #html_additional_pages = {"index": "topindex.html"}
# If false, no module index is generated. # If false, no module index is generated.
#html_domain_indices = True #html_domain_indices = True
@ -316,24 +283,3 @@ texinfo_documents = [
# Example configuration for intersphinx: refer to the Python standard library. # Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'http://docs.python.org/': None} intersphinx_mapping = {'http://docs.python.org/': None}
# Append the other ports' specific folders/files to the exclude pattern
exclude_patterns.extend([port + '*' for port in ports if port != micropy_port])
modules_port_specific = {
'pyboard': ['pyb'],
'wipy': ['wipy'],
'esp8266': ['esp'],
}
modindex_exclude = []
for p, l in modules_port_specific.items():
if p != micropy_port:
modindex_exclude += l
# Exclude extra modules per port
modindex_exclude += {
'esp8266': ['cmath', 'select'],
'wipy': ['cmath'],
}.get(micropy_port, [])

180
docs/Makefile
View File

@ -1,180 +0,0 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = build/$(MICROPY_PORT)
# Run "make FORCE= ..." to avoid rebuilding from scratch (and risk
# producing incorrect docs).
FORCE = -E
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) $(FORCE) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/MicroPython.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/MicroPython.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/MicroPython"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/MicroPython"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) $(FORCE) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

32
docs/README.md
View File

@ -1,16 +1,16 @@
MicroPython Documentation Adafruit's MicroPython Documentation
========================= =========================
The MicroPython documentation can be found at: The latest documentation can be found at:
http://docs.micropython.org/en/latest/ http://adafruit-micropython.readthedocs.io/en/latest/
The documentation you see there is generated from the files in the docs tree: The documentation you see there is generated from the files in the whole tree:
https://github.com/micropython/micropython/tree/master/docs https://github.com/adafruit/micropython/tree/master
Building the documentation locally Building the documentation locally
---------------------------------- ----------------------------------
If you're making changes to the documentation, you may want to build the If you're making changes to the documentation, you should build the
documentation locally so that you can preview your changes. documentation locally so that you can preview your changes.
Install Sphinx, and optionally (for the RTD-styling), sphinx_rtd_theme, Install Sphinx, and optionally (for the RTD-styling), sphinx_rtd_theme,
@ -19,22 +19,8 @@ preferably in a virtualenv:
pip install sphinx pip install sphinx
pip install sphinx_rtd_theme pip install sphinx_rtd_theme
In `micropython/docs`, build the docs: In `micropython/`, build the docs:
make MICROPY_PORT=<port_name> html sphinx-build -v -b html . _build/html
Where `<port_name>` can be `unix`, `pyboard`, `wipy` or `esp8266`. You'll find the index page at `micropython/docs/_build/html/index.html`.
You'll find the index page at `micropython/docs/build/<port_name>/html/index.html`.
PDF manual generation
---------------------
This can be achieved with:
make MICROPY_PORT=<port_name> latexpdf
but require rather complete install of LaTeX with various extensions. On
Debian/Ubuntu, try (500MB+ download):
apt-get install texlive-latex-recommended texlive-latex-extra

10
docs/c2rst.py Normal file
View File

@ -0,0 +1,10 @@
import sphinx.parsers
import docutils.parsers.rst as rst
class CStrip(sphinx.parsers.Parser):
def __init(self):
self.rst_parser = rst.Parser()
def parse(self, inputstring, document):
print(inputstring)
self.rst_parser(stripped, document)

9
docs/drivers.rst Normal file
View File

@ -0,0 +1,9 @@
Adafruit MicroPython drivers
========================================
These are drivers available in separate GitHub repos.
.. toctree::
RGB Displays <http://micropython-rgb.readthedocs.io/en/latest/index.html>
Analog-to-digital converters: ADS1015 and ADS1115 <http://micropython-ads1015.readthedocs.io/>

8
docs/esp8266/index.rst Normal file
View File

@ -0,0 +1,8 @@
ESP8266
========================================
.. toctree::
quickref.rst
general.rst
tutorial/index.rst

11
docs/esp8266_contents.rst
View File

@ -1,11 +0,0 @@
MicroPython documentation contents
==================================
.. toctree::
esp8266/quickref.rst
esp8266/general.rst
esp8266/tutorial/index.rst
library/index.rst
reference/index.rst
license.rst

16
docs/esp8266_index.rst
View File

@ -1,16 +0,0 @@
MicroPython documentation and references
========================================
.. toctree::
esp8266/quickref.rst
library/index.rst
license.rst
esp8266_contents.rst
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

242
docs/make.bat
View File

@ -1,242 +0,0 @@
@ECHO OFF
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set BUILDDIR=_build
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
set I18NSPHINXOPTS=%SPHINXOPTS% .
if NOT "%PAPER%" == "" (
set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
)
if "%1" == "" goto help
if "%1" == "help" (
:help
echo.Please use `make ^<target^>` where ^<target^> is one of
echo. html to make standalone HTML files
echo. dirhtml to make HTML files named index.html in directories
echo. singlehtml to make a single large HTML file
echo. pickle to make pickle files
echo. json to make JSON files
echo. htmlhelp to make HTML files and a HTML help project
echo. qthelp to make HTML files and a qthelp project
echo. devhelp to make HTML files and a Devhelp project
echo. epub to make an epub
echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
echo. text to make text files
echo. man to make manual pages
echo. texinfo to make Texinfo files
echo. gettext to make PO message catalogs
echo. changes to make an overview over all changed/added/deprecated items
echo. xml to make Docutils-native XML files
echo. pseudoxml to make pseudoxml-XML files for display purposes
echo. linkcheck to check all external links for integrity
echo. doctest to run all doctests embedded in the documentation if enabled
goto end
)
if "%1" == "clean" (
for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
del /q /s %BUILDDIR%\*
goto end
)
%SPHINXBUILD% 2> nul
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
if "%1" == "html" (
%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/html.
goto end
)
if "%1" == "dirhtml" (
%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
goto end
)
if "%1" == "singlehtml" (
%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
goto end
)
if "%1" == "pickle" (
%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can process the pickle files.
goto end
)
if "%1" == "json" (
%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can process the JSON files.
goto end
)
if "%1" == "htmlhelp" (
%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can run HTML Help Workshop with the ^
.hhp project file in %BUILDDIR%/htmlhelp.
goto end
)
if "%1" == "qthelp" (
%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can run "qcollectiongenerator" with the ^
.qhcp project file in %BUILDDIR%/qthelp, like this:
echo.^> qcollectiongenerator %BUILDDIR%\qthelp\MicroPython.qhcp
echo.To view the help file:
echo.^> assistant -collectionFile %BUILDDIR%\qthelp\MicroPython.ghc
goto end
)
if "%1" == "devhelp" (
%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished.
goto end
)
if "%1" == "epub" (
%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The epub file is in %BUILDDIR%/epub.
goto end
)
if "%1" == "latex" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
if errorlevel 1 exit /b 1
echo.
echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "latexpdf" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
cd %BUILDDIR%/latex
make all-pdf
cd %BUILDDIR%/..
echo.
echo.Build finished; the PDF files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "latexpdfja" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
cd %BUILDDIR%/latex
make all-pdf-ja
cd %BUILDDIR%/..
echo.
echo.Build finished; the PDF files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "text" (
%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The text files are in %BUILDDIR%/text.
goto end
)
if "%1" == "man" (
%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The manual pages are in %BUILDDIR%/man.
goto end
)
if "%1" == "texinfo" (
%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
goto end
)
if "%1" == "gettext" (
%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
goto end
)
if "%1" == "changes" (
%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
if errorlevel 1 exit /b 1
echo.
echo.The overview file is in %BUILDDIR%/changes.
goto end
)
if "%1" == "linkcheck" (
%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
if errorlevel 1 exit /b 1
echo.
echo.Link check complete; look for any errors in the above output ^
or in %BUILDDIR%/linkcheck/output.txt.
goto end
)
if "%1" == "doctest" (
%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
if errorlevel 1 exit /b 1
echo.
echo.Testing of doctests in the sources finished, look at the ^
results in %BUILDDIR%/doctest/output.txt.
goto end
)
if "%1" == "xml" (
%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The XML files are in %BUILDDIR%/xml.
goto end
)
if "%1" == "pseudoxml" (
%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
goto end
)
:end

9
docs/pyboard/index.rst Normal file
View File

@ -0,0 +1,9 @@
PyBoard
========================================
.. toctree::
quickref.rst
general.rst
tutorial/index.rst
hardware/index.rst

13
docs/pyboard_contents.rst
View File

@ -1,13 +0,0 @@
MicroPython documentation contents
==================================
.. toctree::
pyboard/quickref.rst
pyboard/general.rst
pyboard/tutorial/index.rst
library/index.rst
reference/index.rst
pyboard/hardware/index.rst
license.rst

19
docs/pyboard_index.rst
View File

@ -1,19 +0,0 @@
MicroPython documentation and references
========================================
.. toctree::
pyboard/quickref.rst
pyboard/general.rst
pyboard/tutorial/index.rst
library/index.rst
pyboard/hardware/index.rst
license.rst
pyboard_contents.rst
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

10
docs/supported_ports.rst Normal file
View File

@ -0,0 +1,10 @@
Supported Ports
==============================
Adafruit's MicroPython derivative currently has limited support with a focus on
the Atmel SAMD21 port
.. toctree::
:maxdepth: 2
atmel-samd/README.md

120
docs/topindex.html
View File

@ -1,120 +0,0 @@
{% extends "defindex.html" %}
{% block body %}
<h1>MicroPython documentation</h1>
<p>
{{ _('Welcome! This is the documentation for MicroPython') }}
v{{ release|e }}{% if last_updated %}, {{ _('last updated') }} {{ last_updated|e }}{% endif %}.
</p>
<p>
MicroPython runs on a variety of systems and each has their own specific
documentation. You are currently viewing the documentation for
<strong>{{ port_name }}</strong>.
</p>
<!--p>
Documentation for other systems are available:
{% for p in all_ports %}
<a href="{{ p[1] }}">{{ p[0] }}</a>{% if not loop.last %}, {% endif %}
{% endfor %}.
</p-->
<p><strong>Documentation for MicroPython and {{ port_name }}:</strong></p>
<table class="contentstable"><tr>
<td width="40%" style="padding-left:2em;">
{% if port in ("pyboard", "wipy", "esp8266") %}
<p class="biglink">
<a class="biglink" href="{{ pathto(port + "/quickref") }}">Quick reference for {{ port_name }}</a><br/>
<span class="linkdescr">pinout for {{ port_name }} and snippets of useful code</span>
</p>
<p class="biglink">
<a class="biglink" href="{{ pathto(port + "/general") }}">General information about {{ port_name }}</a><br/>
<span class="linkdescr">read this first for a quick overview</span>
</p>
<p class="biglink">
<a class="biglink" href="{{ pathto(port + "/tutorial/index") }}">Tutorials and code examples</a><br/>
<span class="linkdescr">start here</span>
</p>
{% endif %}
<p class="biglink">
<a class="biglink" href="{{ pathto("library/index") }}">Library Reference</a><br/>
{% if port == "pyboard" %}
<span class="linkdescr">MicroPython libraries, including the <a href="{{ pathto("library/pyb") }}">pyb module</a></span>
{% else %}
<span class="linkdescr">MicroPython libraries, including the <a href="{{ pathto("library/machine") }}">machine module</a></span>
{% endif %}
</p>
</td>
<td width="40%" style="padding-left:2em;">
<p class="biglink">
<a class="biglink" href="{{ pathto("reference/index") }}">Language Reference</a><br/>
<span class="linkdescr">information about MicroPython specific language features</span>
</p>
{% if port == "pyboard" %}
<p class="biglink">
<a class="biglink" href="{{ pathto(port + "/hardware/index") }}">The {{ port }} hardware</a><br/>
<span class="linkdescr">schematics, dimensions and component datasheets</span>
</p>
<p class="biglink">
<a class="biglink" href="http://micropython.org/resources/Micro-Python-Windows-setup.pdf">Guide for {{ port_name }} on Windows (PDF)</a><br/>
<span class="linkdescr">including DFU programming</span>
</p>
{% endif %}
<p class="biglink">
<a class="biglink" href="{{ pathto("license") }}">License</a><br/>
<span class="linkdescr">MicroPython license information</span>
</p>
</td>
</tr></table>
<p><strong>Indices and tables:</strong></p>
<table class="contentstable"><tr>
<td width="40%" style="padding-left:2em;">
<p class="biglink">
<a class="biglink" href="{{ pathto("py-modindex") }}">Module index</a><br/>
<span class="linkdescr">quick access to all modules</span>
</p>
<p class="biglink">
<a class="biglink" href="{{ pathto("genindex") }}">Full index</a><br/>
<span class="linkdescr">all functions, classes, constants</span>
</p>
</td>
<td width="40%" style="padding-left:2em;">
<p class="biglink">
<a class="biglink" href="{{ pathto(port + "_contents") }}">Table of contents</a><br/>
<span class="linkdescr">a list of all sections and subsections</span>
</p>
</td></tr>
</table>
<p><strong>External links:</strong></p>
<table class="contentstable"><tr>
<td width="40%" style="padding-left:2em;">
<p class="biglink">
<a class="biglink" href="http://micropython.org">MicroPython homepage</a><br/>
<span class="linkdescr">the official MicroPython site</span>
</p>
<p class="biglink">
<a class="biglink" href="http://forum.micropython.org">MicroPython forum</a><br/>
<span class="linkdescr">community discussion for all things related to MicroPython</span>
</p>
</td>
<td width="40%" style="padding-left:2em;">
<p class="biglink">
<a class="biglink" href="https://github.com/micropython">MicroPython on GitHub</a><br/>
<span class="linkdescr">contribute to the source code on GitHub</span>
</p>
{% if port == "wipy" %}
<p class="biglink">
<a class="biglink" href="http://wipy.io">The WiPy homepage</a><br/>
<span class="linkdescr">the official WiPy site</span>
</p>
{% endif %}
</td>
</tr></table>
{% endblock %}

8
docs/unix_contents.rst
View File

@ -1,8 +0,0 @@
MicroPython documentation contents
==================================
.. toctree::
library/index.rst
reference/index.rst
license.rst

15
docs/unix_index.rst
View File

@ -1,15 +0,0 @@
MicroPython documentation and references
========================================
.. toctree::
library/index.rst
license.rst
unix_contents.rst
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

15
docs/unsupported_ports.rst Normal file
View File

@ -0,0 +1,15 @@
Unsupported Ports
==============================
Adafruit's MicroPython derivative currently has limited support with a focus on
the Atmel SAMD21 port. The ports below still exist in the code to preserve
upstream compatibility but are not tested. Use at your own risk.
We recommend using `upstream MicroPython <https://micropython.org>`_ for the below ports.
.. toctree::
:maxdepth: 2
esp8266/index.rst
pyboard/index.rst
wipy/index.rst

8
docs/wipy/index.rst Normal file
View File

@ -0,0 +1,8 @@
WiPy
==================================
.. toctree::
quickref.rst
general.rst
tutorial/index.rst

11
docs/wipy_contents.rst
View File

@ -1,11 +0,0 @@
MicroPython documentation contents
==================================
.. toctree::
wipy/quickref.rst
wipy/general.rst
wipy/tutorial/index.rst
library/index.rst
reference/index.rst
license.rst

18
docs/wipy_index.rst
View File

@ -1,18 +0,0 @@
MicroPython documentation and references
========================================
.. toctree::
wipy/quickref.rst
wipy/general.rst
wipy/tutorial/index.rst
library/index.rst
license.rst
wipy_contents.rst
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

33
index.rst Normal file
View File

@ -0,0 +1,33 @@
Adafruit's MicroPython API Reference
========================================
Welcome! This is the documentation for Adafruit's version MicroPython. It is an
open source derivative of MicroPython for use on educational development boards
designed and sold by Adafruit including the Arduino Zero, Adafruit Feather M0
Basic, Adafruit Feather HUZZAH and Adafruit Feather M0 Bluefruit LE.
Adafruit's MicroPython port features a unified Python APIs available under
`shared-bindings` and a growing list of drivers that work with it. Currently
only the Atmel SAMD21 port is supported but ESP8266 support will be added in the
near future.
Adafruit has many excellent tutorials available through the Adafruit Learning
System. These docs are low-level API docs and may link out to separate getting
started guides.
.. toctree::
:maxdepth: 2
shared-bindings/index.rst
docs/drivers.rst
docs/supported_ports.rst
docs/unsupported_ports.rst
docs/library/index.rst
license.rst
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

0
docs/license.rst → license.rst
View File

12
shared-bindings/index.rst Normal file
View File

@ -0,0 +1,12 @@
Shared Libraries
========================================
These core libraries are intended on being consistent across ports. Currently
they are only implemented in the SAMD21 port but the ESP8266 support will soon
follow.
.. toctree::
:glob:
:maxdepth: 3
modules/*

23
shared-bindings/modules/machine.c
View File

@ -34,6 +34,16 @@
#include "py/runtime.h" #include "py/runtime.h"
//| :mod:`machine` --- functions related to the board
//| =================================================
//|
//| .. module:: machine
//| :synopsis: functions related to the board
//|
//| The ``machine`` module contains specific functions related to the board.
//|
//| This is soon to be renamed to distinguish it from upstream's machine!
//|
//| .. currentmodule:: machine //| .. currentmodule:: machine
//| //|
//| class I2C -- a two-wire serial protocol //| class I2C -- a two-wire serial protocol
@ -101,6 +111,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(machine_i2c_obj___exit___obj, 4, 4, m
//| Scan all I2C addresses between 0x08 and 0x77 inclusive and return a list of //| Scan all I2C addresses between 0x08 and 0x77 inclusive and return a list of
//| those that respond. A device responds if it pulls the SDA line low after //| those that respond. A device responds if it pulls the SDA line low after
//| its address (including a read bit) is sent on the bus. //| its address (including a read bit) is sent on the bus.
//|
STATIC mp_obj_t machine_i2c_scan(mp_obj_t self_in) { STATIC mp_obj_t machine_i2c_scan(mp_obj_t self_in) {
machine_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); machine_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in);
mp_obj_t list = mp_obj_new_list(0, NULL); mp_obj_t list = mp_obj_new_list(0, NULL);
@ -125,6 +136,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(machine_i2c_scan_obj, machine_i2c_scan);
//| //|
//| Read `nbytes` from the slave specified by `addr`. //| Read `nbytes` from the slave specified by `addr`.
//| Returns a `bytes` object with the data read. //| Returns a `bytes` object with the data read.
//|
STATIC mp_obj_t machine_i2c_readfrom(mp_obj_t self_in, mp_obj_t addr_in, mp_obj_t nbytes_in) { STATIC mp_obj_t machine_i2c_readfrom(mp_obj_t self_in, mp_obj_t addr_in, mp_obj_t nbytes_in) {
machine_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); machine_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in);
vstr_t vstr; vstr_t vstr;
@ -141,6 +153,7 @@ MP_DEFINE_CONST_FUN_OBJ_3(machine_i2c_readfrom_obj, machine_i2c_readfrom);
//| //|
//| On WiPy the return value is the number of bytes read. Otherwise the //| On WiPy the return value is the number of bytes read. Otherwise the
//| return value is `None`. //| return value is `None`.
//|
STATIC mp_obj_t machine_i2c_readfrom_into(mp_obj_t self_in, mp_obj_t addr_in, mp_obj_t buf_in) { STATIC mp_obj_t machine_i2c_readfrom_into(mp_obj_t self_in, mp_obj_t addr_in, mp_obj_t buf_in) {
machine_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); machine_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in);
mp_buffer_info_t bufinfo; mp_buffer_info_t bufinfo;
@ -153,6 +166,7 @@ MP_DEFINE_CONST_FUN_OBJ_3(machine_i2c_readfrom_into_obj, machine_i2c_readfrom_in
//| .. method:: I2C.writeto(addr, buf) //| .. method:: I2C.writeto(addr, buf)
//| //|
//| Write the bytes from `buf` to the slave specified by `addr`. //| Write the bytes from `buf` to the slave specified by `addr`.
//|
STATIC mp_obj_t machine_i2c_writeto(mp_obj_t self_in, mp_obj_t addr_in, mp_obj_t buf_in) { STATIC mp_obj_t machine_i2c_writeto(mp_obj_t self_in, mp_obj_t addr_in, mp_obj_t buf_in) {
machine_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); machine_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in);
mp_buffer_info_t bufinfo; mp_buffer_info_t bufinfo;
@ -178,6 +192,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_3(machine_i2c_writeto_obj, machine_i2c_writeto);
//| The argument `addrsize` specifies the address size in bits (on ESP8266 //| The argument `addrsize` specifies the address size in bits (on ESP8266
//| this argument is not recognised and the address size is always 8 bits). //| this argument is not recognised and the address size is always 8 bits).
//| Returns a `bytes` object with the data read. //| Returns a `bytes` object with the data read.
//|
STATIC mp_obj_t machine_i2c_readfrom_mem(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { STATIC mp_obj_t machine_i2c_readfrom_mem(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
enum { ARG_addr, ARG_memaddr, ARG_n, ARG_addrsize }; enum { ARG_addr, ARG_memaddr, ARG_n, ARG_addrsize };
static const mp_arg_t allowed_args[] = { static const mp_arg_t allowed_args[] = {
@ -211,6 +226,7 @@ MP_DEFINE_CONST_FUN_OBJ_KW(machine_i2c_readfrom_mem_obj, 1, machine_i2c_readfrom
//| //|
//| On WiPy the return value is the number of bytes read. Otherwise the //| On WiPy the return value is the number of bytes read. Otherwise the
//| return value is `None`. //| return value is `None`.
//|
STATIC mp_obj_t machine_i2c_readfrom_mem_into(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { STATIC mp_obj_t machine_i2c_readfrom_mem_into(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
enum { ARG_addr, ARG_memaddr, ARG_buf, ARG_addrsize }; enum { ARG_addr, ARG_memaddr, ARG_buf, ARG_addrsize };
static const mp_arg_t allowed_args[] = { static const mp_arg_t allowed_args[] = {
@ -242,6 +258,7 @@ MP_DEFINE_CONST_FUN_OBJ_KW(machine_i2c_readfrom_mem_into_obj, 1, machine_i2c_rea
//| //|
//| On WiPy the return value is the number of bytes written. Otherwise the //| On WiPy the return value is the number of bytes written. Otherwise the
//| return value is `None`. //| return value is `None`.
//|
STATIC mp_obj_t machine_i2c_writeto_mem(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { STATIC mp_obj_t machine_i2c_writeto_mem(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
enum { ARG_addr, ARG_memaddr, ARG_buf, ARG_addrsize }; enum { ARG_addr, ARG_memaddr, ARG_buf, ARG_addrsize };
static const mp_arg_t allowed_args[] = { static const mp_arg_t allowed_args[] = {
@ -350,6 +367,7 @@ STATIC mp_obj_t machine_spi_make_new(const mp_obj_type_t *type, size_t n_args, s
//| .. method:: SPI.init() //| .. method:: SPI.init()
//| //|
//| Initialises the bus. //| Initialises the bus.
//|
STATIC mp_obj_t machine_spi_obj_init(mp_obj_t self_in) { STATIC mp_obj_t machine_spi_obj_init(mp_obj_t self_in) {
machine_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); machine_spi_obj_t *self = MP_OBJ_TO_PTR(self_in);
mp_hal_spi_init(self); mp_hal_spi_init(self);
@ -360,6 +378,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(machine_spi_init_obj, machine_spi_obj_init);
//| .. method:: SPI.deinit() //| .. method:: SPI.deinit()
//| //|
//| Turn off the SPI bus. //| Turn off the SPI bus.
//|
STATIC mp_obj_t machine_spi_obj_deinit(mp_obj_t self_in) { STATIC mp_obj_t machine_spi_obj_deinit(mp_obj_t self_in) {
machine_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); machine_spi_obj_t *self = MP_OBJ_TO_PTR(self_in);
mp_hal_spi_deinit(self); mp_hal_spi_deinit(self);
@ -379,6 +398,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(machine_spi_obj___exit___obj, 4, 4, m
//| Write from ``write_buf`` and read into ``read_buf``. Both buffers must have the //| Write from ``write_buf`` and read into ``read_buf``. Both buffers must have the
//| same length. This is the same as a SPI transfer function on other platforms. //| same length. This is the same as a SPI transfer function on other platforms.
//| Returns the number of bytes written //| Returns the number of bytes written
//|
STATIC mp_obj_t mp_machine_spi_write_readinto(mp_obj_t self_in, mp_obj_t wr_buf, mp_obj_t rd_buf) { STATIC mp_obj_t mp_machine_spi_write_readinto(mp_obj_t self_in, mp_obj_t wr_buf, mp_obj_t rd_buf) {
mp_buffer_info_t src; mp_buffer_info_t src;
mp_get_buffer_raise(wr_buf, &src, MP_BUFFER_READ); mp_get_buffer_raise(wr_buf, &src, MP_BUFFER_READ);
@ -402,6 +422,7 @@ MP_DEFINE_CONST_FUN_OBJ_3(mp_machine_spi_write_readinto_obj, mp_machine_spi_writ
//| //|
//| Write the data contained in ``buf``. //| Write the data contained in ``buf``.
//| Returns the number of bytes written. //| Returns the number of bytes written.
//|
STATIC mp_obj_t mp_machine_spi_write(mp_obj_t self_in, mp_obj_t wr_buf) { STATIC mp_obj_t mp_machine_spi_write(mp_obj_t self_in, mp_obj_t wr_buf) {
mp_buffer_info_t src; mp_buffer_info_t src;
mp_get_buffer_raise(wr_buf, &src, MP_BUFFER_READ); mp_get_buffer_raise(wr_buf, &src, MP_BUFFER_READ);
@ -415,6 +436,7 @@ MP_DEFINE_CONST_FUN_OBJ_2(mp_machine_spi_write_obj, mp_machine_spi_write);
//| //|
//| Read the ``nbytes`` while writing the data specified by ``write``. //| Read the ``nbytes`` while writing the data specified by ``write``.
//| Return the number of bytes read. //| Return the number of bytes read.
//|
STATIC mp_obj_t mp_machine_spi_read(size_t n_args, const mp_obj_t *args) { STATIC mp_obj_t mp_machine_spi_read(size_t n_args, const mp_obj_t *args) {
vstr_t vstr; vstr_t vstr;
vstr_init_len(&vstr, mp_obj_get_int(args[1])); vstr_init_len(&vstr, mp_obj_get_int(args[1]));
@ -429,6 +451,7 @@ MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(mp_machine_spi_read_obj, 2, 3, mp_machine_sp
//| Read into the buffer specified by ``buf`` while writing the data specified by //| Read into the buffer specified by ``buf`` while writing the data specified by
//| ``write``. //| ``write``.
//| Return the number of bytes read. //| Return the number of bytes read.
//|
STATIC mp_obj_t mp_machine_spi_readinto(size_t n_args, const mp_obj_t *args) { STATIC mp_obj_t mp_machine_spi_readinto(size_t n_args, const mp_obj_t *args) {
mp_buffer_info_t bufinfo; mp_buffer_info_t bufinfo;
mp_get_buffer_raise(args[1], &bufinfo, MP_BUFFER_WRITE); mp_get_buffer_raise(args[1], &bufinfo, MP_BUFFER_WRITE);