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.

21 files changed, 78 insertions, 1039 deletions

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 <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
-	@echo "  dirhtml    to make HTML files named index.html in directories"
-	@echo "  singlehtml to make a single large HTML file"
-	@echo "  pickle     to make pickle files"
-	@echo "  json       to make JSON files"
-	@echo "  htmlhelp   to make HTML files and a HTML help project"
-	@echo "  qthelp     to make HTML files and a qthelp project"
-	@echo "  devhelp    to make HTML files and a Devhelp project"
-	@echo "  epub       to make an epub"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
-	@echo "  text       to make text files"
-	@echo "  man        to make manual pages"
-	@echo "  texinfo    to make Texinfo files"
-	@echo "  info       to make Texinfo files and run them through makeinfo"
-	@echo "  gettext    to make PO message catalogs"
-	@echo "  changes    to make an overview of all changed/added/deprecated items"
-	@echo "  xml        to make Docutils-native XML files"
-	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
-	@echo "  linkcheck  to check all external links for integrity"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
-
-clean:
-	rm -rf $(BUILDDIR)/*
-
-html:
-	$(SPHINXBUILD) $(FORCE) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
-	@echo
-	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/MicroPython.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/MicroPython.qhc"
-
-devhelp:
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
-	@echo
-	@echo "Build finished."
-	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/MicroPython"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/MicroPython"
-	@echo "# devhelp"
-
-epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make' in that directory to run these through (pdf)latex" \
-	      "(use \`make latexpdf' here to do that automatically)."
-
-latexpdf:
-	$(SPHINXBUILD) $(FORCE) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-latexpdfja:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through platex and dvipdfmx..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-text:
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
-	@echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-man:
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-texinfo:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo
-	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
-	@echo "Run \`make' in that directory to run these through makeinfo" \
-	      "(use \`make info' here to do that automatically)."
-
-info:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo "Running Texinfo files through makeinfo..."
-	make -C $(BUILDDIR)/texinfo info
-	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
-
-gettext:
-	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
-	@echo
-	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
-
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
-
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
-
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
-
-xml:
-	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
-	@echo
-	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
-
-pseudoxml:
-	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
-	@echo
-	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
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=<port_name> html
+    sphinx-build -v -b html . _build/html
 
-Where `<port_name>` can be `unix`, `pyboard`, `wipy` or `esp8266`.
-
-You'll find the index page at `micropython/docs/build/<port_name>/html/index.html`.
-
-PDF manual generation
----------------------
-
-This can be achieved with:
-
-    make MICROPY_PORT=<port_name> latexpdf
-
-but require rather complete install of LaTeX with various extensions. On
-Debian/Ubuntu, try (500MB+ download):
-
-    apt-get install texlive-latex-recommended texlive-latex-extra
+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
-# "<project> v<release> 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 <link> 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 <http://micropython-rgb.readthedocs.io/en/latest/index.html>
+    Analog-to-digital converters: ADS1015 and ADS1115 <http://micropython-ads1015.readthedocs.io/>
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 ^<target^>` where ^<target^> is one of
-	echo.  html       to make standalone HTML files
-	echo.  dirhtml    to make HTML files named index.html in directories
-	echo.  singlehtml to make a single large HTML file
-	echo.  pickle     to make pickle files
-	echo.  json       to make JSON files
-	echo.  htmlhelp   to make HTML files and a HTML help project
-	echo.  qthelp     to make HTML files and a qthelp project
-	echo.  devhelp    to make HTML files and a Devhelp project
-	echo.  epub       to make an epub
-	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
-	echo.  text       to make text files
-	echo.  man        to make manual pages
-	echo.  texinfo    to make Texinfo files
-	echo.  gettext    to make PO message catalogs
-	echo.  changes    to make an overview over all changed/added/deprecated items
-	echo.  xml        to make Docutils-native XML files
-	echo.  pseudoxml  to make pseudoxml-XML files for display purposes
-	echo.  linkcheck  to check all external links for integrity
-	echo.  doctest    to run all doctests embedded in the documentation if enabled
-	goto end
-)
-
-if "%1" == "clean" (
-	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
-	del /q /s %BUILDDIR%\*
-	goto end
-)
-
-
-%SPHINXBUILD% 2> nul
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
-	exit /b 1
-)
-
-if "%1" == "html" (
-	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
-	goto end
-)
-
-if "%1" == "dirhtml" (
-	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
-	goto end
-)
-
-if "%1" == "singlehtml" (
-	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
-	goto end
-)
-
-if "%1" == "pickle" (
-	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can process the pickle files.
-	goto end
-)
-
-if "%1" == "json" (
-	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can process the JSON files.
-	goto end
-)
-
-if "%1" == "htmlhelp" (
-	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can run HTML Help Workshop with the ^
-.hhp project file in %BUILDDIR%/htmlhelp.
-	goto end
-)
-
-if "%1" == "qthelp" (
-	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can run "qcollectiongenerator" with the ^
-.qhcp project file in %BUILDDIR%/qthelp, like this:
-	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\MicroPython.qhcp
-	echo.To view the help file:
-	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\MicroPython.ghc
-	goto end
-)
-
-if "%1" == "devhelp" (
-	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished.
-	goto end
-)
-
-if "%1" == "epub" (
-	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The epub file is in %BUILDDIR%/epub.
-	goto end
-)
-
-if "%1" == "latex" (
-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
-	goto end
-)
-
-if "%1" == "latexpdf" (
-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
-	cd %BUILDDIR%/latex
-	make all-pdf
-	cd %BUILDDIR%/..
-	echo.
-	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
-	goto end
-)
-
-if "%1" == "latexpdfja" (
-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
-	cd %BUILDDIR%/latex
-	make all-pdf-ja
-	cd %BUILDDIR%/..
-	echo.
-	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
-	goto end
-)
-
-if "%1" == "text" (
-	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The text files are in %BUILDDIR%/text.
-	goto end
-)
-
-if "%1" == "man" (
-	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The manual pages are in %BUILDDIR%/man.
-	goto end
-)
-
-if "%1" == "texinfo" (
-	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
-	goto end
-)
-
-if "%1" == "gettext" (
-	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
-	goto end
-)
-
-if "%1" == "changes" (
-	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.The overview file is in %BUILDDIR%/changes.
-	goto end
-)
-
-if "%1" == "linkcheck" (
-	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Link check complete; look for any errors in the above output ^
-or in %BUILDDIR%/linkcheck/output.txt.
-	goto end
-)
-
-if "%1" == "doctest" (
-	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Testing of doctests in the sources finished, look at the ^
-results in %BUILDDIR%/doctest/output.txt.
-	goto end
-)
-
-if "%1" == "xml" (
-	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The XML files are in %BUILDDIR%/xml.
-	goto end
-)
-
-if "%1" == "pseudoxml" (
-	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
-	goto end
-)
-
-:end
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 %}
-
-  <h1>MicroPython documentation</h1>
-
-  <p>
-    {{ _('Welcome! This is the documentation for MicroPython') }}
-    v{{ release|e }}{% if last_updated %}, {{ _('last updated') }} {{ last_updated|e }}{% endif %}.
-  </p>
-
-  <p>
-    MicroPython runs on a variety of systems and each has their own specific
-    documentation.  You are currently viewing the documentation for
-    <strong>{{ port_name }}</strong>.
-  </p>
-
-  <!--p>
-    Documentation for other systems are available:
-    {% for p in all_ports %}
-      <a href="{{ p[1] }}">{{ p[0] }}</a>{% if not loop.last %}, {% endif %}
-    {% endfor %}.
-  </p-->
-
-  <p><strong>Documentation for MicroPython and {{ port_name }}:</strong></p>
-
-  <table class="contentstable"><tr>
-    <td width="40%" style="padding-left:2em;">
-      {% if port in ("pyboard", "wipy", "esp8266") %}
-        <p class="biglink">
-          <a class="biglink" href="{{ pathto(port + "/quickref") }}">Quick reference for {{ port_name }}</a><br/>
-          <span class="linkdescr">pinout for {{ port_name }} and snippets of useful code</span>
-        </p>
-        <p class="biglink">
-          <a class="biglink" href="{{ pathto(port + "/general") }}">General information about {{ port_name }}</a><br/>
-          <span class="linkdescr">read this first for a quick overview</span>
-        </p>
-        <p class="biglink">
-          <a class="biglink" href="{{ pathto(port + "/tutorial/index") }}">Tutorials and code examples</a><br/>
-          <span class="linkdescr">start here</span>
-        </p>
-      {% endif %}
-      <p class="biglink">
-        <a class="biglink" href="{{ pathto("library/index") }}">Library Reference</a><br/>
-        {% if port == "pyboard" %}
-          <span class="linkdescr">MicroPython libraries, including the <a href="{{ pathto("library/pyb") }}">pyb module</a></span>
-        {% else %}
-          <span class="linkdescr">MicroPython libraries, including the <a href="{{ pathto("library/machine") }}">machine module</a></span>
-        {% endif %}
-      </p>
-    </td>
-    <td width="40%" style="padding-left:2em;">
-      <p class="biglink">
-        <a class="biglink" href="{{ pathto("reference/index") }}">Language Reference</a><br/>
-        <span class="linkdescr">information about MicroPython specific language features</span>
-      </p>
-      {% if port == "pyboard" %}
-        <p class="biglink">
-            <a class="biglink" href="{{ pathto(port + "/hardware/index") }}">The {{ port }} hardware</a><br/>
-            <span class="linkdescr">schematics, dimensions and component datasheets</span>
-        </p>
-        <p class="biglink">
-            <a class="biglink" href="http://micropython.org/resources/Micro-Python-Windows-setup.pdf">Guide for {{ port_name }} on Windows (PDF)</a><br/>
-            <span class="linkdescr">including DFU programming</span>
-        </p>
-      {% endif %}
-      <p class="biglink">
-        <a class="biglink" href="{{ pathto("license") }}">License</a><br/>
-        <span class="linkdescr">MicroPython license information</span>
-      </p>
-    </td>
-  </tr></table>
-
-  <p><strong>Indices and tables:</strong></p>
-  <table class="contentstable"><tr>
-    <td width="40%" style="padding-left:2em;">
-      <p class="biglink">
-        <a class="biglink" href="{{ pathto("py-modindex") }}">Module index</a><br/>
-        <span class="linkdescr">quick access to all modules</span>
-      </p>
-      <p class="biglink">
-        <a class="biglink" href="{{ pathto("genindex") }}">Full index</a><br/>
-        <span class="linkdescr">all functions, classes, constants</span>
-      </p>
-    </td>
-    <td width="40%" style="padding-left:2em;">
-      <p class="biglink">
-        <a class="biglink" href="{{ pathto(port + "_contents") }}">Table of contents</a><br/>
-        <span class="linkdescr">a list of all sections and subsections</span>
-      </p>
-    </td></tr>
-  </table>
-
-  <p><strong>External links:</strong></p>
-
-  <table class="contentstable"><tr>
-    <td width="40%" style="padding-left:2em;">
-      <p class="biglink">
-      <a class="biglink" href="http://micropython.org">MicroPython homepage</a><br/>
-        <span class="linkdescr">the official MicroPython site</span>
-      </p>
-      <p class="biglink">
-        <a class="biglink" href="http://forum.micropython.org">MicroPython forum</a><br/>
-        <span class="linkdescr">community discussion for all things related to MicroPython</span>
-      </p>
-    </td>
-    <td width="40%" style="padding-left:2em;">
-      <p class="biglink">
-        <a class="biglink" href="https://github.com/micropython">MicroPython on GitHub</a><br/>
-        <span class="linkdescr">contribute to the source code on GitHub</span>
-      </p>
-      {% if port == "wipy" %}
-        <p class="biglink">
-          <a class="biglink" href="http://wipy.io">The WiPy homepage</a><br/>
-          <span class="linkdescr">the official WiPy site</span>
-        </p>
-      {% endif %}
-    </td>
-  </tr></table>
-
-{% endblock %}
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 <https://micropython.org>`_ 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`