docs: Make custom index page; add more docs.

docs/conf.py

@@ -113,7 +113,7 @@ html_theme = 'default'
 #html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+html_theme_path = ['.']
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -124,7 +124,7 @@ html_theme = 'default'
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+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
@@ -154,7 +154,7 @@ html_theme = 'default'
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
-#html_additional_pages = {}
+html_additional_pages = {"index":"topindex.html"}
 
 # If false, no module index is generated.
 #html_domain_indices = True

docs/contents.rst

@@ -0,0 +1,11 @@
+Micro Python documentation contents
+===================================
+
+.. toctree::
+
+   quickref.rst
+   general.rst
+   tutorial/index.rst
+   library/index.rst
+   hardware/index.rst
+   license.rst

docs/hardware/index.rst

@@ -0,0 +1,13 @@
+The pyboard hardware
+====================
+
+* `PYBv1.0 schematics and layout <http://micropython.org/static/doc/PYBv10b.pdf>`_ (2.4MiB PDF)
+* `PYBv1.0 metric dimensions <http://micropython.org/static/doc/PYBv10b-metric-dimensions.pdf>`_ (360KiB PDF)
+* `PYBv1.0 imperial dimensions <http://micropython.org/static/doc/PYBv10b-imperial-dimensions.pdf>`_ (360KiB PDF)
+
+Datasheets for the components on the pyboard
+============================================
+
+* The microcontroller: `STM32F405RGT6 <http://www.st.com/web/catalog/mmc/FM141/SC1169/SS1577/LN1035/PF252144>`_ (link to manufacturer's site)
+* The accelerometer: `Freescale MMA7660 <http://micropython.org/static/doc/MMA7660FC.pdf>`_ (800kiB PDF)
+* The LDO voltage regulator: `Microchip MCP1802 <http://micropython.org/static/doc/MCP1802-22053C.pdf>`_ (400kiB PDF)

docs/index.rst

@@ -1,44 +1,15 @@
-.. Micro Python documentation master file
-
 Micro Python documentation and references
 =========================================
 
-Here you can find documentation for Micro Python and the pyboard.
-
 .. toctree::
-   :maxdepth: 1
 
    quickref.rst
-
-Software
---------
-
-.. toctree::
-   :maxdepth: 1
-
    general.rst
    tutorial/index.rst
    library/index.rst
-
+   hardware/index.rst
-.. 
+   license.rst
-..  - Reference for the [pyb module](module/pyb/ "pyb module").
+   contents.rst
-..  - Reference for [all modules](module/ "all modules").
-..  - [Guide for setting up the pyboard on Windows](/static/doc/Micro-Python-Windows-setup.pdf), including DFU programming (PDF).
-
-The pyboard hardware
---------------------
-
-..  - PYBv1.0 [schematics and layout](/static/doc/PYBv10b.pdf "PYBv1.0") (2.4MiB PDF).
-..  - PYBv1.0 [metric dimensions](/static/doc/PYBv10b-metric-dimensions.pdf "metric dimensions") (360KiB PDF).
-..  - PYBv1.0 [imperial dimensions](/static/doc/PYBv10b-imperial-dimensions.pdf "imperial dimensions") (360KiB PDF).
-
-Datasheets for the components on the pyboard
---------------------------------------------
-
-..  - The microcontroller: [STM32F405RGT6](http://www.st.com/web/catalog/mmc/FM141/SC1169/SS1577/LN1035/PF252144) (external link).
-..  - The accelerometer: [Freescale MMA7660](/static/doc/MMA7660FC.pdf) (800kiB PDF).
-..  - The LDO voltage regulator: [Microchip MCP1802](/static/doc/MCP1802-22053C.pdf) (400kiB PDF).
-
 
 Indices and tables
 ==================
@@ -46,4 +17,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

docs/library/index.rst

@@ -4,6 +4,11 @@ Micro Python libraries
 Python standard libraries
 -------------------------
 
+The following standard Python libraries are built in to Micro Python.
+
+For additional libraries, please download them from the `micropython-lib repository
+<https://github.com/micropython/micropython-lib>`_.
+
 .. toctree::
    :maxdepth: 1
 
@@ -12,11 +17,23 @@ Python standard libraries
    math.rst
    os.rst
    select.rst
+   struct.rst
    sys.rst
    time.rst
 
-Micro Python reduced libraries
+Python micro-libraries
-------------------------------
+----------------------
+
+The following standard Python libraries have been "micro-ified" to fit in with
+the philosophy of Micro Python.  They provide the core functionality of that
+module and are intended to be a drop-in replacement for the standard Python
+library.
+
+The modules are available by their u-name, and also by their non-u-name.  The
+non-u-name can be overridden by a file of that name in your package path.
+For example, ``import json`` will first search for a file ``json.py`` or
+directory ``json`` and load that package if it is found.  If nothing is found,
+it will fallback to loading the built-in ``ujson`` module.
 
 .. toctree::
    :maxdepth: 1
@@ -28,6 +45,8 @@ Micro Python reduced libraries
 Libraries specific to the pyboard
 ---------------------------------
 
+The following libraries are specific to the pyboard.
+
 .. toctree::
    :maxdepth: 2
 

docs/library/pyb.SPI.rst

@@ -93,18 +93,12 @@ Methods
 Constants
 ---------
 
-.. data:: LSB
+.. data:: SPI.MASTER
+.. data:: SPI.SLAVE
 
-   set the first bit to LSB
+   for initialising the SPI bus to master or slave mode
 
-.. data:: MASTER
+.. data:: SPI.LSB
+.. data:: SPI.MSB
 
-   for initialising the bus to master mode
+   set the first bit to be the least or most significant bit
-
-.. data:: MSB
-
-   set the first bit to MSB
-
-.. data:: SLAVE
-
-   for initialising the bus to slave mode

docs/library/struct.rst

@@ -0,0 +1,25 @@
+:mod:`struct` -- pack and unpack primitive data types
+=====================================================
+
+.. module:: struct
+   :synopsis: pack and unpack primitive data types
+
+See `Python struct <https://docs.python.org/3/library/struct.html>`_ for more
+information.
+
+Functions
+---------
+
+.. function:: calcsize(fmt)
+
+   Return the number of bytes needed to store the given ``fmt``.
+
+.. function:: pack(fmt, v1, v2, ...)
+
+   Pack the values ``v1``, ``v2``, ... according to the format string ``fmt``.
+   The return value is a bytes object encoding the values.
+
+.. function:: unpack(fmt, data)
+
+   Unpack from the ``data`` according to the format string ``fmt``.
+   The return value is a tuple of the unpacked values.

docs/license.rst

@@ -0,0 +1,24 @@
+Micro Python license information
+================================
+
+The MIT License (MIT)
+
+Copyright (c) 2013, 2014 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.

docs/topindex.html

@@ -0,0 +1,84 @@
+{% extends "defindex.html" %}
+{% block tables %}
+  <p><strong>Documentation for Micro Python and the pyboard:</strong></p>
+
+  <table class="contentstable" align="center"><tr>
+    <td width="50%">
+      <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>
+      <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="50%">
+      <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/static/doc/Micro-Python-Windows-setup.pdf">Guide for pyboard on Windows (PDF)</a><br/>
+        <span class="linkdescr">including DFU programming</span>
+      </p>
+      <p class="biglink">
+        <a class="biglink" href="{{ pathto("license") }}">License</a><br/>
+        <span class="linkdescr">Micro Python license information</span>
+      </p>
+    </td>
+  </tr></table>
+
+  <p><strong>Indices and tables:</strong></p>
+  <table class="contentstable" align="center"><tr>
+    <td width="50%">
+      <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="50%">
+      <p class="biglink">
+        <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>
+
+  <p><strong>External links:</strong></p>
+
+  <table class="contentstable" align="center"><tr>
+    <td width="50%">
+      <p class="biglink">
+      <a class="biglink" href="http://micropython.org">Micro Python homepage</a><br/>
+        <span class="linkdescr">the official Micro Python site</span>
+      </p>
+      <p class="biglink">
+        <a class="biglink" href="http://forum.micropython.org">Micro Python forum</a><br/>
+        <span class="linkdescr">community discussion for all things related to Micro Python</span>
+      </p>
+    </td>
+    <td width="50%">
+      <p class="biglink">
+        <a class="biglink" href="https://github.com/micropython">Micro Python on GitHub</a><br/>
+        <span class="linkdescr">contribute to the source code on GitHub</span>
+      </p>
+    </td>
+  </tr></table>
+
+{% endblock %}

docs/tutorial/amp_skin.rst

@@ -51,11 +51,11 @@ For example::
     dac.write_timed(buf, 400 * len(buf), mode=DAC.CIRCULAR)
 
 You can also play WAV files using the Python ``wave`` module.  You can get
-the wave module [here](/static/doc/examples/wave.py) and you will also need
+the wave module `here <http://micropython.org/static/doc/examples/wave.py>`_ and you will also need
-the chunk module available [here](/static/doc/examples/chunk.py).  Put these
+the chunk module available `here <http://micropython.org/static/doc/examples/chunk.py>`_.  Put these
 on your pyboard (either on the flash or the SD card in the top-level
 directory).  You will need an 8-bit WAV file to play, such as
-[this one](/static/doc/examples/test.wav).  Then you can do::
+`this one <http://micropython.org/static/doc/examples/test.wav>`_.  Then you can do::
 
     >>> import wave
     >>> from pyb import DAC

docs/tutorial/index.rst

@@ -24,15 +24,6 @@ the tutorial through in the order below.
    assembler.rst
    power_ctrl.rst
 
-Tips, tricks and useful things to know
---------------------------------------
-
-.. toctree::
-   :maxdepth: 1
-   :numbered:
-
-   pass_through.rst
-
 Tutorials requiring extra components
 ------------------------------------
 
@@ -44,3 +35,12 @@ Tutorials requiring extra components
    fading_led.rst
    lcd_skin.rst
    amp_skin.rst
+
+Tips, tricks and useful things to know
+--------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+   :numbered:
+
+   pass_through.rst

docs/tutorial/lcd_skin.rst

@@ -58,7 +58,7 @@ enables the 4 touch sensors.  The third line reads the touch
 status and the ``touch`` variable holds the state of the 4 touch
 buttons (A, B, X, Y).
 
-There is a simple driver [here](/static/doc/examples/mpr121.py)
+There is a simple driver `here <http://micropython.org/static/doc/examples/mpr121.py>`_
 which allows you to set the threshold and debounce parameters, and
 easily read the touch status and electrode voltage levels.  Copy
 this script to your pyboard (either flash or SD card, in the top
@@ -81,4 +81,4 @@ initialise the I2C bus using::
     >>> m = mpr121.MPR121(pyb.I2C(2, pyb.I2C.MASTER))
 
 There is also a demo which uses the LCD and the touch sensors together,
-and can be found [here](/static/doc/examples/lcddemo.py).
+and can be found `here <http://micropython.org/static/doc/examples/lcddemo.py>`_.

docs/tutorial/repl.rst

@@ -26,7 +26,7 @@ and see which COM port it is (eg COM4).
 
 You now need to run your terminal program.  You can use HyperTerminal if you
 have it installed, or download the free program PuTTY:
-[`putty.exe`](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html).
+`putty.exe <http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html>`_.
 Using your serial program you must connect to the COM port that you found in the
 previous step.  With PuTTY, click on "Session" in the left-hand panel, then click
 the "Serial" radio button on the right, then enter you COM port (eg COM4) in the

docs/tutorial/script.rst

@@ -46,16 +46,16 @@ a window (or command line) should be showing the files on the pyboard drive.
 The drive you are looking at is known as ``/flash`` by the pyboard, and should contain
 the following 4 files:
 
-  - [``boot.py``](/static/doc/fresh-pyboard/boot.py) -- this script is executed when the pyboard boots up.  It sets
+* `boot.py <http://micropython.org/static/doc/fresh-pyboard/boot.py>`_ -- this script is executed when the pyboard boots up.  It sets
     up various configuration options for the pyboard.
 
-  - [``main.py``](/static/doc/fresh-pyboard/main.py) -- this is the main script that will contain your Python program.
+* `main.py <http://micropython.org/static/doc/fresh-pyboard/main.py>`_ -- this is the main script that will contain your Python program.
     It is executed after ``boot.py``.
 
-  - [``README.txt``](/static/doc/fresh-pyboard/README.txt) -- this contains some very basic information about getting
+* `README.txt <http://micropython.org/static/doc/fresh-pyboard/README.txt>`_ -- this contains some very basic information about getting
     started with the pyboard.
 
-  - [``pybcdc.inf``](/static/doc/fresh-pyboard/pybcdc.inf) -- this is a Windows driver file to configure the serial USB
+* `pybcdc.inf <http://micropython.org/static/doc/fresh-pyboard/pybcdc.inf>`_ -- this is a Windows driver file to configure the serial USB
     device.  More about this in the next tutorial.
 
 Editing ``main.py``