djsundog/circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Make custom index page; add more docs.

Browse Source
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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/conf.py
View File

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

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)

36
docs/index.rst
View File

@ -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
..
.. - Reference for the [pyb module](module/pyb/ "pyb module").
.. - 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).
hardware/index.rst
license.rst
contents.rst
Indices and tables
==================
@ -46,4 +17,3 @@ Indices and tables
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

23
docs/library/index.rst
View File

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

18
docs/library/pyb.SPI.rst
View File

@ -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
.. data:: MSB
set the first bit to MSB
.. data:: SLAVE
for initialising the bus to slave mode
set the first bit to be the least or most significant bit

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

6
docs/tutorial/amp_skin.rst
View File

@ -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 chunk module available [here](/static/doc/examples/chunk.py). Put these
the wave module `here <http://micropython.org/static/doc/examples/wave.py>`_ and you will also need
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

18
docs/tutorial/index.rst
View File

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

4
docs/tutorial/lcd_skin.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
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>`_.

2
docs/tutorial/repl.rst
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
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

8
docs/tutorial/script.rst
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 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``