docs: Make custom index page; add more docs.

This commit is contained in:
Damien George 2014-11-02 23:37:02 +00:00
parent 1060baa2c2
commit 6e6dfdc56b
14 changed files with 209 additions and 69 deletions

View File

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

11
docs/contents.rst Normal file
View File

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

13
docs/hardware/index.rst Normal file
View File

@ -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)

View File

@ -1,44 +1,15 @@
.. Micro Python documentation master file
Micro Python documentation and references Micro Python documentation and references
========================================= =========================================
Here you can find documentation for Micro Python and the pyboard.
.. toctree:: .. toctree::
:maxdepth: 1
quickref.rst quickref.rst
Software
--------
.. toctree::
:maxdepth: 1
general.rst general.rst
tutorial/index.rst tutorial/index.rst
library/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 Indices and tables
================== ==================
@ -46,4 +17,3 @@ Indices and tables
* :ref:`genindex` * :ref:`genindex`
* :ref:`modindex` * :ref:`modindex`
* :ref:`search` * :ref:`search`

View File

@ -4,6 +4,11 @@ Micro Python libraries
Python standard 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:: .. toctree::
:maxdepth: 1 :maxdepth: 1
@ -12,11 +17,23 @@ Python standard libraries
math.rst math.rst
os.rst os.rst
select.rst select.rst
struct.rst
sys.rst sys.rst
time.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:: .. toctree::
:maxdepth: 1 :maxdepth: 1
@ -28,6 +45,8 @@ Micro Python reduced libraries
Libraries specific to the pyboard Libraries specific to the pyboard
--------------------------------- ---------------------------------
The following libraries are specific to the pyboard.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2

View File

@ -93,18 +93,12 @@ Methods
Constants 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

25
docs/library/struct.rst Normal file
View File

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

24
docs/license.rst Normal file
View File

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

84
docs/topindex.html Normal file
View File

@ -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 %}

View File

@ -51,11 +51,11 @@ For example::
dac.write_timed(buf, 400 * len(buf), mode=DAC.CIRCULAR) dac.write_timed(buf, 400 * len(buf), mode=DAC.CIRCULAR)
You can also play WAV files using the Python ``wave`` module. You can get 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 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 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 >>> import wave
>>> from pyb import DAC >>> from pyb import DAC

View File

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

View File

@ -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 status and the ``touch`` variable holds the state of the 4 touch
buttons (A, B, X, Y). 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 which allows you to set the threshold and debounce parameters, and
easily read the touch status and electrode voltage levels. Copy easily read the touch status and electrode voltage levels. Copy
this script to your pyboard (either flash or SD card, in the top 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)) >>> m = mpr121.MPR121(pyb.I2C(2, pyb.I2C.MASTER))
There is also a demo which uses the LCD and the touch sensors together, 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>`_.

View File

@ -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 You now need to run your terminal program. You can use HyperTerminal if you
have it installed, or download the free program PuTTY: 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 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 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 the "Serial" radio button on the right, then enter you COM port (eg COM4) in the

View File

@ -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 drive you are looking at is known as ``/flash`` by the pyboard, and should contain
the following 4 files: 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. 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``. 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. 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. device. More about this in the next tutorial.
Editing ``main.py`` Editing ``main.py``