From 46e7f8e4fb172207121516f5bd15d162aedd041d Mon Sep 17 00:00:00 2001 From: Scott Shawcroft Date: Tue, 18 Oct 2016 17:42:47 -0700 Subject: [PATCH] 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 +++ docs/conf.py => conf.py | 76 ++-------- docs/Makefile | 180 ---------------------- docs/README.md | 32 ++-- docs/c2rst.py | 10 ++ docs/drivers.rst | 9 ++ docs/esp8266/index.rst | 8 + docs/esp8266_contents.rst | 11 -- docs/esp8266_index.rst | 16 -- 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 ++++ docs/license.rst => license.rst | 0 shared-bindings/index.rst | 12 ++ shared-bindings/modules/machine.c | 33 +++- 26 files changed, 183 insertions(+), 746 deletions(-) create mode 100644 c2rst.py rename docs/conf.py => conf.py (81%) mode change 100755 => 100644 delete mode 100644 docs/Makefile create mode 100644 docs/c2rst.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/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 rename docs/license.rst => license.rst (100%) create mode 100644 shared-bindings/index.rst diff --git a/.gitignore b/.gitignore index 9102a6bc63..7770297c1a 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 0000000000..6b0fe646a2 --- /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/docs/conf.py b/conf.py old mode 100755 new mode 100644 similarity index 81% rename from docs/conf.py rename to conf.py index a737e43ef1..134ecf1cf3 --- a/docs/conf.py +++ b/conf.py @@ -21,46 +21,14 @@ import os # 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' +master_doc = 'index' # -- General configuration ------------------------------------------------ # 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 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -70,17 +38,16 @@ extensions = [ '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', + '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' +source_suffix = ['.rst', '.md', '.c', '.h'] + +source_parsers = {'.c': "c2rst.CStrip", '.h': "c2rst.CStrip"} # The encoding of source files. #source_encoding = 'utf-8-sig' @@ -89,8 +56,8 @@ source_suffix = '.rst' #master_doc = 'index' # General information about the project. -project = 'MicroPython' -copyright = '2014-2016, Damien P. George and contributors' +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 @@ -113,7 +80,7 @@ release = '1.8.4' # List of patterns, relative to source directory, that match files and # 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 # documents. @@ -183,7 +150,7 @@ else: # 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'] +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 @@ -203,7 +170,7 @@ html_last_updated_fmt = '%d %b %Y' # Additional templates that should be rendered to pages, maps page names to # template names. -html_additional_pages = {"index": "topindex.html"} +#html_additional_pages = {"index": "topindex.html"} # If false, no module index is generated. #html_domain_indices = True @@ -316,24 +283,3 @@ texinfo_documents = [ # 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/Makefile b/docs/Makefile deleted file mode 100644 index d81d11eeb2..0000000000 --- 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 faf386710a..6e79258110 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 0000000000..3018e62aff --- /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/drivers.rst b/docs/drivers.rst new file mode 100644 index 0000000000..7db3fbd753 --- /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 0000000000..63cf65c614 --- /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 30def3df2b..0000000000 --- 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 82de9d6dfd..0000000000 --- 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/make.bat b/docs/make.bat deleted file mode 100644 index 44f9682790..0000000000 --- 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 0000000000..c05e5d47fe --- /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 5ced479efc..0000000000 --- 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 38ccb1ac99..0000000000 --- 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 0000000000..a92be3a7c2 --- /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 75039233ee..0000000000 --- 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 ec0a6f0e86..0000000000 --- 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 027f24c2e3..0000000000 --- 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 0000000000..7ace37155c --- /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 0000000000..9b355d4963 --- /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 2beffa236e..0000000000 --- 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 9fe3dce896..0000000000 --- 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 0000000000..689854547b --- /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/docs/license.rst b/license.rst similarity index 100% rename from docs/license.rst rename to license.rst diff --git a/shared-bindings/index.rst b/shared-bindings/index.rst new file mode 100644 index 0000000000..42394febeb --- /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 b16ab8aae8..d2fd97ff1f 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);