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

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

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)

docs/conf.py → conf.py

@@ -21,46 +21,14 @@
 # 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 @@
     '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 @@
 #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 @@
 
 # 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 @@
 # 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 @@
 
 # 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 @@
 
 # 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, [])

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`.