From 46e7f8e4fb172207121516f5bd15d162aedd041d Mon Sep 17 00:00:00 2001 From: Scott Shawcroft Date: Tue, 18 Oct 2016 17:42:47 -0700 Subject: Documentation rework to unify the docs together rather than having them 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. --- .gitignore | 4 + c2rst.py | 17 ++ conf.py | 285 ++++++++++++++++++++++++++++++++ docs/Makefile | 180 -------------------- docs/README.md | 32 +--- docs/c2rst.py | 10 ++ docs/conf.py | 339 -------------------------------------- docs/drivers.rst | 9 + docs/esp8266/index.rst | 8 + docs/esp8266_contents.rst | 11 -- docs/esp8266_index.rst | 16 -- docs/license.rst | 24 --- docs/make.bat | 242 --------------------------- docs/pyboard/index.rst | 9 + docs/pyboard_contents.rst | 13 -- docs/pyboard_index.rst | 19 --- docs/supported_ports.rst | 10 ++ docs/topindex.html | 120 -------------- docs/unix_contents.rst | 8 - docs/unix_index.rst | 15 -- docs/unsupported_ports.rst | 15 ++ docs/wipy/index.rst | 8 + docs/wipy_contents.rst | 11 -- docs/wipy_index.rst | 18 -- index.rst | 33 ++++ license.rst | 24 +++ shared-bindings/index.rst | 12 ++ shared-bindings/modules/machine.c | 33 +++- 28 files changed, 481 insertions(+), 1044 deletions(-) create mode 100644 c2rst.py create mode 100644 conf.py delete mode 100644 docs/Makefile create mode 100644 docs/c2rst.py delete mode 100755 docs/conf.py create mode 100644 docs/drivers.rst create mode 100644 docs/esp8266/index.rst delete mode 100644 docs/esp8266_contents.rst delete mode 100644 docs/esp8266_index.rst delete mode 100644 docs/license.rst delete mode 100644 docs/make.bat create mode 100644 docs/pyboard/index.rst delete mode 100644 docs/pyboard_contents.rst delete mode 100644 docs/pyboard_index.rst create mode 100644 docs/supported_ports.rst delete mode 100644 docs/topindex.html delete mode 100644 docs/unix_contents.rst delete mode 100644 docs/unix_index.rst create mode 100644 docs/unsupported_ports.rst create mode 100644 docs/wipy/index.rst delete mode 100644 docs/wipy_contents.rst delete mode 100644 docs/wipy_index.rst create mode 100644 index.rst create mode 100644 license.rst create mode 100644 shared-bindings/index.rst diff --git a/.gitignore b/.gitignore index 9102a6bc6..7770297c1 100644 --- a/.gitignore +++ b/.gitignore @@ -39,3 +39,7 @@ __pycache__/ ###################### GNUmakefile user.props + +# Sphinx output +############### +_build diff --git a/c2rst.py b/c2rst.py new file mode 100644 index 000000000..6b0fe646a --- /dev/null +++ b/c2rst.py @@ -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) diff --git a/conf.py b/conf.py new file mode 100644 index 000000000..134ecf1cf --- /dev/null +++ b/conf.py @@ -0,0 +1,285 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# MicroPython documentation build configuration file, created by +# sphinx-quickstart on Sun Sep 21 11:42:03 2014. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os + +# 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 +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('.')) + + +# Specify a custom master document based on the port name +master_doc = 'index' + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +needs_sphinx = '1.3' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.coverage' +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['templates'] + +# The suffix of source filenames. +source_suffix = ['.rst', '.md', '.c', '.h'] + +source_parsers = {'.c': "c2rst.CStrip", '.h': "c2rst.CStrip"} + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +#master_doc = 'index' + +# General information about the project. +project = 'Adafruit\'s MicroPython' +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 +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.8' +# The full version, including alpha/beta/rc tags. +release = '1.8.4' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +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 +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# on_rtd is whether we are on readthedocs.org +on_rtd = os.environ.get('READTHEDOCS', None) == 'True' + +if not on_rtd: # only import and set the theme if we're building docs locally + try: + import sphinx_rtd_theme + html_theme = 'sphinx_rtd_theme' + html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), '.'] + except: + html_theme = 'default' + html_theme_path = ['.'] +else: + html_theme_path = ['.'] + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +# html_theme_path = ['.'] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = '../../logo/trans-logo.png' + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# 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, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['docs/static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +html_last_updated_fmt = '%d %b %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {"index": "topindex.html"} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'MicroPythondoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'MicroPython.tex', 'MicroPython Documentation', + 'Damien P. George and contributors', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'micropython', 'MicroPython Documentation', + ['Damien P. George and contributors'], 1), +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'MicroPython', 'MicroPython Documentation', + 'Damien P. George and contributors', 'MicroPython', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d81d11eeb..000000000 --- a/docs/Makefile +++ /dev/null @@ -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 ' where 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." diff --git a/docs/README.md b/docs/README.md index faf386710..6e7925811 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,16 +1,16 @@ -MicroPython Documentation +Adafruit's MicroPython Documentation ========================= -The MicroPython documentation can be found at: -http://docs.micropython.org/en/latest/ +The latest documentation can be found at: +http://adafruit-micropython.readthedocs.io/en/latest/ -The documentation you see there is generated from the files in the docs tree: -https://github.com/micropython/micropython/tree/master/docs +The documentation you see there is generated from the files in the whole tree: +https://github.com/adafruit/micropython/tree/master 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. 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_rtd_theme -In `micropython/docs`, build the docs: +In `micropython/`, build the docs: - make MICROPY_PORT= html + sphinx-build -v -b html . _build/html -Where `` can be `unix`, `pyboard`, `wipy` or `esp8266`. - -You'll find the index page at `micropython/docs/build//html/index.html`. - -PDF manual generation ---------------------- - -This can be achieved with: - - make MICROPY_PORT= 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 +You'll find the index page at `micropython/docs/_build/html/index.html`. diff --git a/docs/c2rst.py b/docs/c2rst.py new file mode 100644 index 000000000..3018e62af --- /dev/null +++ b/docs/c2rst.py @@ -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) diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100755 index a737e43ef..000000000 --- a/docs/conf.py +++ /dev/null @@ -1,339 +0,0 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- -# -# MicroPython documentation build configuration file, created by -# sphinx-quickstart on Sun Sep 21 11:42:03 2014. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys -import os - -# 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 -# documentation root, use os.path.abspath to make it absolute, like shown here. -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 -master_doc = micropy_port + '_' + 'index' - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.doctest', - 'sphinx.ext.intersphinx', - 'sphinx.ext.todo', - '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. -templates_path = ['templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -#master_doc = 'index' - -# General information about the project. -project = 'MicroPython' -copyright = '2014-2016, Damien P. George and contributors' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '1.8' -# The full version, including alpha/beta/rc tags. -release = '1.8.4' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['build'] - -# The reST default role (used for this markup: `text`) to use for all -# documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False - - -# -- Options for HTML output ---------------------------------------------- - -# on_rtd is whether we are on readthedocs.org -on_rtd = os.environ.get('READTHEDOCS', None) == 'True' - -if not on_rtd: # only import and set the theme if we're building docs locally - try: - import sphinx_rtd_theme - html_theme = 'sphinx_rtd_theme' - html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), '.'] - except: - html_theme = 'default' - html_theme_path = ['.'] -else: - html_theme_path = ['.'] - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -# html_theme_path = ['.'] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = '../../logo/trans-logo.png' - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# 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, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['static'] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -#html_extra_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -html_last_updated_fmt = '%d %b %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -html_additional_pages = {"index": "topindex.html"} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'MicroPythondoc' - - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'MicroPython.tex', 'MicroPython Documentation', - 'Damien P. George and contributors', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'micropython', 'MicroPython Documentation', - ['Damien P. George and contributors'], 1), -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'MicroPython', 'MicroPython Documentation', - 'Damien P. George and contributors', 'MicroPython', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False - - -# Example configuration for intersphinx: refer to the Python standard library. -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, []) diff --git a/docs/drivers.rst b/docs/drivers.rst new file mode 100644 index 000000000..7db3fbd75 --- /dev/null +++ b/docs/drivers.rst @@ -0,0 +1,9 @@ +Adafruit MicroPython drivers +======================================== + +These are drivers available in separate GitHub repos. + +.. toctree:: + + RGB Displays + Analog-to-digital converters: ADS1015 and ADS1115 diff --git a/docs/esp8266/index.rst b/docs/esp8266/index.rst new file mode 100644 index 000000000..63cf65c61 --- /dev/null +++ b/docs/esp8266/index.rst @@ -0,0 +1,8 @@ +ESP8266 +======================================== + +.. toctree:: + + quickref.rst + general.rst + tutorial/index.rst diff --git a/docs/esp8266_contents.rst b/docs/esp8266_contents.rst deleted file mode 100644 index 30def3df2..000000000 --- a/docs/esp8266_contents.rst +++ /dev/null @@ -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 diff --git a/docs/esp8266_index.rst b/docs/esp8266_index.rst deleted file mode 100644 index 82de9d6df..000000000 --- a/docs/esp8266_index.rst +++ /dev/null @@ -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` diff --git a/docs/license.rst b/docs/license.rst deleted file mode 100644 index bbc5016ed..000000000 --- a/docs/license.rst +++ /dev/null @@ -1,24 +0,0 @@ -MicroPython license information -=============================== - -The MIT License (MIT) - -Copyright (c) 2013-2015 Damien P. George, and others - -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. diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 44f968279..000000000 --- a/docs/make.bat +++ /dev/null @@ -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 ^` where ^ 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 diff --git a/docs/pyboard/index.rst b/docs/pyboard/index.rst new file mode 100644 index 000000000..c05e5d47f --- /dev/null +++ b/docs/pyboard/index.rst @@ -0,0 +1,9 @@ +PyBoard +======================================== + +.. toctree:: + + quickref.rst + general.rst + tutorial/index.rst + hardware/index.rst diff --git a/docs/pyboard_contents.rst b/docs/pyboard_contents.rst deleted file mode 100644 index 5ced479ef..000000000 --- a/docs/pyboard_contents.rst +++ /dev/null @@ -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 - diff --git a/docs/pyboard_index.rst b/docs/pyboard_index.rst deleted file mode 100644 index 38ccb1ac9..000000000 --- a/docs/pyboard_index.rst +++ /dev/null @@ -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` diff --git a/docs/supported_ports.rst b/docs/supported_ports.rst new file mode 100644 index 000000000..a92be3a7c --- /dev/null +++ b/docs/supported_ports.rst @@ -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 diff --git a/docs/topindex.html b/docs/topindex.html deleted file mode 100644 index 75039233e..000000000 --- a/docs/topindex.html +++ /dev/null @@ -1,120 +0,0 @@ -{% extends "defindex.html" %} -{% block body %} - -

MicroPython documentation

- -

- {{ _('Welcome! This is the documentation for MicroPython') }} - v{{ release|e }}{% if last_updated %}, {{ _('last updated') }} {{ last_updated|e }}{% endif %}. -

- -

- MicroPython runs on a variety of systems and each has their own specific - documentation. You are currently viewing the documentation for - {{ port_name }}. -

- - - -

Documentation for MicroPython and {{ port_name }}:

- - - - -
- {% if port in ("pyboard", "wipy", "esp8266") %} -

- Quick reference for {{ port_name }}
- pinout for {{ port_name }} and snippets of useful code -

-

- General information about {{ port_name }}
- read this first for a quick overview -

-

- Tutorials and code examples
- start here -

- {% endif %} -

- Library Reference
- {% if port == "pyboard" %} - MicroPython libraries, including the pyb module - {% else %} - MicroPython libraries, including the machine module - {% endif %} -

- 		-

- Language Reference
- information about MicroPython specific language features -

- {% if port == "pyboard" %} -

- The {{ port }} hardware
- schematics, dimensions and component datasheets -

-

- Guide for {{ port_name }} on Windows (PDF)
- including DFU programming -

- {% endif %} -

- License
- MicroPython license information -

-
- -

Indices and tables:

- - - -
-

- Module index
- quick access to all modules -

-

- Full index
- all functions, classes, constants -

- 		-

- Table of contents
- a list of all sections and subsections -

-
- -

External links:

- - - - -
-

- MicroPython homepage
- the official MicroPython site -

-

- MicroPython forum
- community discussion for all things related to MicroPython -

- 		-

- MicroPython on GitHub
- contribute to the source code on GitHub -

- {% if port == "wipy" %} -

- The WiPy homepage
- the official WiPy site -

- {% endif %} -
- -{% endblock %} diff --git a/docs/unix_contents.rst b/docs/unix_contents.rst deleted file mode 100644 index ec0a6f0e8..000000000 --- a/docs/unix_contents.rst +++ /dev/null @@ -1,8 +0,0 @@ -MicroPython documentation contents -================================== - -.. toctree:: - - library/index.rst - reference/index.rst - license.rst diff --git a/docs/unix_index.rst b/docs/unix_index.rst deleted file mode 100644 index 027f24c2e..000000000 --- a/docs/unix_index.rst +++ /dev/null @@ -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` diff --git a/docs/unsupported_ports.rst b/docs/unsupported_ports.rst new file mode 100644 index 000000000..7ace37155 --- /dev/null +++ b/docs/unsupported_ports.rst @@ -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 `_ for the below ports. + +.. toctree:: + :maxdepth: 2 + + esp8266/index.rst + pyboard/index.rst + wipy/index.rst diff --git a/docs/wipy/index.rst b/docs/wipy/index.rst new file mode 100644 index 000000000..9b355d496 --- /dev/null +++ b/docs/wipy/index.rst @@ -0,0 +1,8 @@ +WiPy +================================== + +.. toctree:: + + quickref.rst + general.rst + tutorial/index.rst diff --git a/docs/wipy_contents.rst b/docs/wipy_contents.rst deleted file mode 100644 index 2beffa236..000000000 --- a/docs/wipy_contents.rst +++ /dev/null @@ -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 diff --git a/docs/wipy_index.rst b/docs/wipy_index.rst deleted file mode 100644 index 9fe3dce89..000000000 --- a/docs/wipy_index.rst +++ /dev/null @@ -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` diff --git a/index.rst b/index.rst new file mode 100644 index 000000000..689854547 --- /dev/null +++ b/index.rst @@ -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` diff --git a/license.rst b/license.rst new file mode 100644 index 000000000..bbc5016ed --- /dev/null +++ b/license.rst @@ -0,0 +1,24 @@ +MicroPython license information +=============================== + +The MIT License (MIT) + +Copyright (c) 2013-2015 Damien P. George, and others + +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. diff --git a/shared-bindings/index.rst b/shared-bindings/index.rst new file mode 100644 index 000000000..42394febe --- /dev/null +++ b/shared-bindings/index.rst @@ -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/* diff --git a/shared-bindings/modules/machine.c b/shared-bindings/modules/machine.c index b16ab8aae..d2fd97ff1 100644 --- a/shared-bindings/modules/machine.c +++ b/shared-bindings/modules/machine.c @@ -34,6 +34,16 @@ #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 //| //| class I2C -- a two-wire serial protocol @@ -48,10 +58,10 @@ //| //| Constructors //| ------------ -//| .. class:: I2C(scl, sda, \*, freq=400000) +//| .. class:: I2C(scl, sda, \*, freq=400000) //| -//| Construct and return a new I2C object. -//| See the init method below for a description of the arguments. +//| Construct and return a new I2C object. +//| See the init method below for a description of the arguments. STATIC mp_obj_t machine_i2c_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *pos_args) { mp_arg_check_num(n_args, n_kw, 0, MP_OBJ_FUN_ARGS_MAX, true); machine_i2c_obj_t *self = m_new_obj(machine_i2c_obj_t); @@ -73,7 +83,7 @@ STATIC mp_obj_t machine_i2c_make_new(const mp_obj_type_t *type, size_t n_args, s return (mp_obj_t)self; } -//| .. method:: I2C.init() +//| .. method:: I2C.init() STATIC mp_obj_t machine_i2c_obj_init(mp_obj_t self_in) { machine_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); mp_hal_i2c_init(self); @@ -81,7 +91,7 @@ STATIC mp_obj_t machine_i2c_obj_init(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(machine_i2c_init_obj, machine_i2c_obj_init); -//| .. method:: I2C.deinit() +//| .. method:: I2C.deinit() STATIC mp_obj_t machine_i2c_obj_deinit(mp_obj_t self_in) { machine_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); mp_hal_i2c_deinit(self); @@ -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 //| 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. +//| STATIC mp_obj_t machine_i2c_scan(mp_obj_t self_in) { machine_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); 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`. //| 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) { machine_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); 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 //| 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) { machine_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); 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) //| //| 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) { machine_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); 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 //| this argument is not recognised and the address size is always 8 bits). //| 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) { enum { ARG_addr, ARG_memaddr, ARG_n, ARG_addrsize }; 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 //| 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) { enum { ARG_addr, ARG_memaddr, ARG_buf, ARG_addrsize }; 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 //| 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) { enum { ARG_addr, ARG_memaddr, ARG_buf, ARG_addrsize }; 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() //| //| Initialises the bus. +//| STATIC mp_obj_t machine_spi_obj_init(mp_obj_t self_in) { machine_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); 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() //| //| Turn off the SPI bus. +//| STATIC mp_obj_t machine_spi_obj_deinit(mp_obj_t self_in) { machine_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); 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 //| same length. This is the same as a SPI transfer function on other platforms. //| 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) { mp_buffer_info_t src; 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``. //| Returns the number of bytes written. +//| STATIC mp_obj_t mp_machine_spi_write(mp_obj_t self_in, mp_obj_t wr_buf) { mp_buffer_info_t src; 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``. //| Return the number of bytes read. +//| STATIC mp_obj_t mp_machine_spi_read(size_t n_args, const mp_obj_t *args) { vstr_t vstr; 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 //| ``write``. //| Return the number of bytes read. +//| STATIC mp_obj_t mp_machine_spi_readinto(size_t n_args, const mp_obj_t *args) { mp_buffer_info_t bufinfo; mp_get_buffer_raise(args[1], &bufinfo, MP_BUFFER_WRITE); -- cgit v1.2.3