From 6e6dfdc56be2a5d6476d087043d2a4ccae139af2 Mon Sep 17 00:00:00 2001 From: Damien George Date: Sun, 2 Nov 2014 23:37:02 +0000 Subject: [PATCH] docs: Make custom index page; add more docs. --- docs/conf.py | 6 +-- docs/contents.rst | 11 +++++ docs/hardware/index.rst | 13 ++++++ docs/index.rst | 36 ++-------------- docs/library/index.rst | 23 ++++++++++- docs/library/pyb.SPI.rst | 18 +++----- docs/library/struct.rst | 25 ++++++++++++ docs/license.rst | 24 +++++++++++ docs/topindex.html | 84 ++++++++++++++++++++++++++++++++++++++ docs/tutorial/amp_skin.rst | 6 +-- docs/tutorial/index.rst | 18 ++++---- docs/tutorial/lcd_skin.rst | 4 +- docs/tutorial/repl.rst | 2 +- docs/tutorial/script.rst | 8 ++-- 14 files changed, 209 insertions(+), 69 deletions(-) create mode 100644 docs/contents.rst create mode 100644 docs/hardware/index.rst create mode 100644 docs/library/struct.rst create mode 100644 docs/license.rst create mode 100644 docs/topindex.html diff --git a/docs/conf.py b/docs/conf.py index 021ed68444..5f61b8d0b5 100644 --- a/docs/conf.py +++ b/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 # " v 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 diff --git a/docs/contents.rst b/docs/contents.rst new file mode 100644 index 0000000000..e5d3ad3297 --- /dev/null +++ b/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 diff --git a/docs/hardware/index.rst b/docs/hardware/index.rst new file mode 100644 index 0000000000..c934e226c0 --- /dev/null +++ b/docs/hardware/index.rst @@ -0,0 +1,13 @@ +The pyboard hardware +==================== + +* `PYBv1.0 schematics and layout `_ (2.4MiB PDF) +* `PYBv1.0 metric dimensions `_ (360KiB PDF) +* `PYBv1.0 imperial dimensions `_ (360KiB PDF) + +Datasheets for the components on the pyboard +============================================ + +* The microcontroller: `STM32F405RGT6 `_ (link to manufacturer's site) +* The accelerometer: `Freescale MMA7660 `_ (800kiB PDF) +* The LDO voltage regulator: `Microchip MCP1802 `_ (400kiB PDF) diff --git a/docs/index.rst b/docs/index.rst index e72b995865..c11677efd5 100644 --- a/docs/index.rst +++ b/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 - -.. -.. - 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` - diff --git a/docs/library/index.rst b/docs/library/index.rst index 8a93b8c4d0..eb6a466255 100644 --- a/docs/library/index.rst +++ b/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 +`_. + .. 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 diff --git a/docs/library/pyb.SPI.rst b/docs/library/pyb.SPI.rst index 7ad3a90e2d..7b765e6b06 100644 --- a/docs/library/pyb.SPI.rst +++ b/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 - -.. 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 diff --git a/docs/library/struct.rst b/docs/library/struct.rst new file mode 100644 index 0000000000..71ee5c9b70 --- /dev/null +++ b/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 `_ 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. diff --git a/docs/license.rst b/docs/license.rst new file mode 100644 index 0000000000..ce065d2f11 --- /dev/null +++ b/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. diff --git a/docs/topindex.html b/docs/topindex.html new file mode 100644 index 0000000000..c9c2d2d049 --- /dev/null +++ b/docs/topindex.html @@ -0,0 +1,84 @@ +{% extends "defindex.html" %} +{% block tables %} +

Documentation for Micro Python and the pyboard:

+ + + + +
+

+ Quick reference for the pyboard
+ pinout for the pyboard and snippets of useful code +

+

+ General information about the pyboard
+ read this first for a quick overview +

+

+ Tutorials and code examples
+ start here +

+

+ Library Reference
+ Micro Python libraries, including the pyb module +

+ 		+

+ The pyboard hardware
+ schematics, dimensions and component datasheets +

+

+ Guide for pyboard on Windows (PDF)
+ including DFU programming +

+

+ License
+ Micro Python license information +

+
+ +

Indices and tables:

+ + +
+

+ Module index
+ quick access to all modules +

+

+ Full index
+ all functions, classes, constants +

+ 		+

+ Table of contents
+ a list of all sections and subsections +

+

+ Search page
+ search this documentation +

+
+ +

External links:

+ + + + +
+

+ Micro Python homepage
+ the official Micro Python site +

+

+ Micro Python forum
+ community discussion for all things related to Micro Python +

+ 		+

+ Micro Python on GitHub
+ contribute to the source code on GitHub +

+
+ +{% endblock %} diff --git a/docs/tutorial/amp_skin.rst b/docs/tutorial/amp_skin.rst index 66513a5b2a..fbf0bde2d3 100644 --- a/docs/tutorial/amp_skin.rst +++ b/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 chunk module available [here](/static/doc/examples/chunk.py). Put these +the wave module `here `_ and you will also need +the chunk module available `here `_. 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 `_. Then you can do:: >>> import wave >>> from pyb import DAC diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 19e48b5cad..ed1137e1be 100644 --- a/docs/tutorial/index.rst +++ b/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 diff --git a/docs/tutorial/lcd_skin.rst b/docs/tutorial/lcd_skin.rst index 997c1c6f46..288b63162a 100644 --- a/docs/tutorial/lcd_skin.rst +++ b/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 `_ 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 `_. diff --git a/docs/tutorial/repl.rst b/docs/tutorial/repl.rst index 345a0893ee..7874eeff2f 100644 --- a/docs/tutorial/repl.rst +++ b/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 `_. 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 diff --git a/docs/tutorial/script.rst b/docs/tutorial/script.rst index 5f70b72507..d1b12ae6d1 100644 --- a/docs/tutorial/script.rst +++ b/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 `_ -- 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 `_ -- 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 `_ -- 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 `_ -- this is a Windows driver file to configure the serial USB device. More about this in the next tutorial. Editing ``main.py``