docs: Generate a separate docs build for each port.

Using Damien's approach where conf.py and topindex.html are
shared by all ports.

Author: Daniel Campora

docs/conf.py

@@ -134,7 +134,7 @@
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = '../logo/trans-logo.png'
+#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
@@ -277,3 +277,23 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'http://docs.python.org/': None}
+
+
+# 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", "esp8266"),
+))
+
+# The members of the html_context dict are available inside topindex.html
+url_prefix = os.getenv('MICROPY_URL_PREFIX') or '/'
+html_context = {
+    'port':micropy_port,
+    'port_name':ports[micropy_port],
+    'all_ports':[(n, url_prefix + p) for p, n in ports.items()],
+}

docs/contents.rst

@@ -1,11 +1,20 @@
 Micro Python documentation contents
 ===================================
 
-.. toctree::
-
-   quickref.rst
-   general.rst
-   tutorial/index.rst
-   library/index.rst
-   hardware/index.rst
-   license.rst
+.. only:: port_pyboard
+
+    .. toctree::
+
+        pyboard/quickref.rst
+        pyboard/general.rst
+        pyboard/tutorial/index.rst
+        library/index.rst
+        pyboard/hardware/index.rst
+        license.rst
+
+.. only:: port_esp8266
+
+    .. toctree::
+
+        library/index.rst
+        license.rst

docs/index.rst

@@ -1,15 +1,25 @@
 Micro Python documentation and references
 =========================================
 
-.. toctree::
-
-   quickref.rst
-   general.rst
-   tutorial/index.rst
-   library/index.rst
-   hardware/index.rst
-   license.rst
-   contents.rst
+.. only:: port_pyboard
+
+    .. toctree::
+
+        pyboard/quickref.rst
+        pyboard/general.rst
+        pyboard/tutorial/index.rst
+        library/index.rst
+        pyboard/hardware/index.rst
+        license.rst
+        contents.rst
+
+.. only:: port_esp8266
+
+    .. toctree::
+
+        library/index.rst
+        license.rst
+        contents.rst
 
 Indices and tables
 ==================

docs/general.rst renamed to docs/pyboard/general.rst

@@ -8,36 +8,53 @@ <h1>Micro Python documentation</h1>
     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 Micro Python and the pyboard:</strong></p>
 
   <table class="contentstable"><tr>
     <td width="40%" style="padding-left:2em;">
-      <p class="biglink">
-        <a class="biglink" href="{{ pathto("quickref") }}">Quick reference for the pyboard</a><br/>
-        <span class="linkdescr">pinout for the pyboard and snippets of useful code</span>
-      </p>
-      <p class="biglink">
-        <a class="biglink" href="{{ pathto("general") }}">General information about the pyboard</a><br/>
-        <span class="linkdescr">read this first for a quick overview</span>
-      </p>
-      <p class="biglink">
-        <a class="biglink" href="{{ pathto("tutorial/index") }}">Tutorials and code examples</a><br/>
-        <span class="linkdescr">start here</span>
-      </p>
+      {% if port == "pyboard" %}
+        <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/>
         <span class="linkdescr">Micro Python libraries, including the <a href="{{ pathto("library/pyb") }}">pyb module</a></span>
       </p>
     </td>
     <td width="40%" style="padding-left:2em;">
-      <p class="biglink">
-        <a class="biglink" href="{{ pathto("hardware/index") }}">The pyboard 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 pyboard on Windows (PDF)</a><br/>
-        <span class="linkdescr">including DFU programming</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">Micro Python license information</span>
@@ -62,10 +79,6 @@ <h1>Micro Python documentation</h1>
         <a class="biglink" href="{{ pathto("contents") }}">Table of contents</a><br/>
         <span class="linkdescr">a list of all sections and subsections</span>
       </p>
-      <p class="biglink">
-        <a class="biglink" href="{{ pathto("search") }}">Search page</a><br/>
-        <span class="linkdescr">search this documentation</span>
-      </p>
     </td></tr>
   </table>