Skip to content

Commit 6e6dfdc

Browse files
dpgeorgedpgeorge
committed
docs: Make custom index page; add more docs.
1 parent 1060baa commit 6e6dfdc

File tree

14 files changed

+209
-69
lines changed

14 files changed

+209
-69
lines changed

‎docs/conf.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,7 @@
113113
#html_theme_options = {}
114114

115115
# Add any paths that contain custom themes here, relative to this directory.
116-
#html_theme_path = []
116+
html_theme_path = ['.']
117117

118118
# The name for this set of Sphinx documents. If None, it defaults to
119119
# "<project> v<release> documentation".
@@ -124,7 +124,7 @@
124124

125125
# The name of an image file (relative to this directory) to place at the top
126126
# of the sidebar.
127-
#html_logo = None
127+
html_logo = '../logo/trans-logo.png'
128128

129129
# The name of an image file (within the static path) to use as favicon of the
130130
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -154,7 +154,7 @@
154154

155155
# Additional templates that should be rendered to pages, maps page names to
156156
# template names.
157-
#html_additional_pages = {}
157+
html_additional_pages = {"index":"topindex.html"}
158158

159159
# If false, no module index is generated.
160160
#html_domain_indices = True

‎docs/contents.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
Micro Python documentation contents
2+
===================================
3+
4+
.. toctree::
5+
6+
quickref.rst
7+
general.rst
8+
tutorial/index.rst
9+
library/index.rst
10+
hardware/index.rst
11+
license.rst

‎docs/hardware/index.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
The pyboard hardware
2+
====================
3+
4+
* `PYBv1.0 schematics and layout <http://micropython.org/static/doc/PYBv10b.pdf>`_ (2.4MiB PDF)
5+
* `PYBv1.0 metric dimensions <http://micropython.org/static/doc/PYBv10b-metric-dimensions.pdf>`_ (360KiB PDF)
6+
* `PYBv1.0 imperial dimensions <http://micropython.org/static/doc/PYBv10b-imperial-dimensions.pdf>`_ (360KiB PDF)
7+
8+
Datasheets for the components on the pyboard
9+
============================================
10+
11+
* The microcontroller: `STM32F405RGT6 <http://www.st.com/web/catalog/mmc/FM141/SC1169/SS1577/LN1035/PF252144>`_ (link to manufacturer's site)
12+
* The accelerometer: `Freescale MMA7660 <http://micropython.org/static/doc/MMA7660FC.pdf>`_ (800kiB PDF)
13+
* The LDO voltage regulator: `Microchip MCP1802 <http://micropython.org/static/doc/MCP1802-22053C.pdf>`_ (400kiB PDF)

‎docs/index.rst‎

Lines changed: 3 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,19 @@
1-
.. Micro Python documentation master file
2-
31
Micro Python documentation and references
42
=========================================
53

6-
Here you can find documentation for Micro Python and the pyboard.
7-
84
.. toctree::
9-
:maxdepth: 1
105

116
quickref.rst
12-
13-
Software
14-
--------
15-
16-
.. toctree::
17-
:maxdepth: 1
18-
197
general.rst
208
tutorial/index.rst
219
library/index.rst
22-
23-
..
24-
.. - Reference for the [pyb module](module/pyb/ "pyb module").
25-
.. - Reference for [all modules](module/ "all modules").
26-
.. - [Guide for setting up the pyboard on Windows](/static/doc/Micro-Python-Windows-setup.pdf), including DFU programming (PDF).
27-
28-
The pyboard hardware
29-
--------------------
30-
31-
.. - PYBv1.0 [schematics and layout](/static/doc/PYBv10b.pdf "PYBv1.0") (2.4MiB PDF).
32-
.. - PYBv1.0 [metric dimensions](/static/doc/PYBv10b-metric-dimensions.pdf "metric dimensions") (360KiB PDF).
33-
.. - PYBv1.0 [imperial dimensions](/static/doc/PYBv10b-imperial-dimensions.pdf "imperial dimensions") (360KiB PDF).
34-
35-
Datasheets for the components on the pyboard
36-
--------------------------------------------
37-
38-
.. - The microcontroller: [STM32F405RGT6](http://www.st.com/web/catalog/mmc/FM141/SC1169/SS1577/LN1035/PF252144) (external link).
39-
.. - The accelerometer: [Freescale MMA7660](/static/doc/MMA7660FC.pdf) (800kiB PDF).
40-
.. - The LDO voltage regulator: [Microchip MCP1802](/static/doc/MCP1802-22053C.pdf) (400kiB PDF).
41-
10+
hardware/index.rst
11+
license.rst
12+
contents.rst
4213

4314
Indices and tables
4415
==================
4516

4617
* :ref:`genindex`
4718
* :ref:`modindex`
4819
* :ref:`search`
49-

‎docs/library/index.rst‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,11 @@ Micro Python libraries
44
Python standard libraries
55
-------------------------
66

7+
The following standard Python libraries are built in to Micro Python.
8+
9+
For additional libraries, please download them from the `micropython-lib repository
10+
<https://github.com/micropython/micropython-lib>`_.
11+
712
.. toctree::
813
:maxdepth: 1
914

@@ -12,11 +17,23 @@ Python standard libraries
1217
math.rst
1318
os.rst
1419
select.rst
20+
struct.rst
1521
sys.rst
1622
time.rst
1723

18-
Micro Python reduced libraries
19-
------------------------------
24+
Python micro-libraries
25+
----------------------
26+
27+
The following standard Python libraries have been "micro-ified" to fit in with
28+
the philosophy of Micro Python. They provide the core functionality of that
29+
module and are intended to be a drop-in replacement for the standard Python
30+
library.
31+
32+
The modules are available by their u-name, and also by their non-u-name. The
33+
non-u-name can be overridden by a file of that name in your package path.
34+
For example, ``import json`` will first search for a file ``json.py`` or
35+
directory ``json`` and load that package if it is found. If nothing is found,
36+
it will fallback to loading the built-in ``ujson`` module.
2037

2138
.. toctree::
2239
:maxdepth: 1
@@ -28,6 +45,8 @@ Micro Python reduced libraries
2845
Libraries specific to the pyboard
2946
---------------------------------
3047

48+
The following libraries are specific to the pyboard.
49+
3150
.. toctree::
3251
:maxdepth: 2
3352

‎docs/library/pyb.SPI.rst‎

Lines changed: 6 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -93,18 +93,12 @@ Methods
9393
Constants
9494
---------
9595

96-
.. data:: LSB
96+
.. data:: SPI.MASTER
97+
.. data:: SPI.SLAVE
9798

98-
set the first bit to LSB
99+
for initialising the SPI bus to master or slave mode
99100

100-
.. data:: MASTER
101+
.. data:: SPI.LSB
102+
.. data:: SPI.MSB
101103

102-
for initialising the bus to master mode
103-
104-
.. data:: MSB
105-
106-
set the first bit to MSB
107-
108-
.. data:: SLAVE
109-
110-
for initialising the bus to slave mode
104+
set the first bit to be the least or most significant bit

‎docs/library/struct.rst‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
:mod:`struct` -- pack and unpack primitive data types
2+
=====================================================
3+
4+
.. module:: struct
5+
:synopsis: pack and unpack primitive data types
6+
7+
See `Python struct <https://docs.python.org/3/library/struct.html>`_ for more
8+
information.
9+
10+
Functions
11+
---------
12+
13+
.. function:: calcsize(fmt)
14+
15+
Return the number of bytes needed to store the given ``fmt``.
16+
17+
.. function:: pack(fmt, v1, v2, ...)
18+
19+
Pack the values ``v1``, ``v2``, ... according to the format string ``fmt``.
20+
The return value is a bytes object encoding the values.
21+
22+
.. function:: unpack(fmt, data)
23+
24+
Unpack from the ``data`` according to the format string ``fmt``.
25+
The return value is a tuple of the unpacked values.

‎docs/license.rst‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
Micro Python license information
2+
================================
3+
4+
The MIT License (MIT)
5+
6+
Copyright (c) 2013, 2014 Damien P. George, and others
7+
8+
Permission is hereby granted, free of charge, to any person obtaining a copy
9+
of this software and associated documentation files (the "Software"), to deal
10+
in the Software without restriction, including without limitation the rights
11+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
12+
copies of the Software, and to permit persons to whom the Software is
13+
furnished to do so, subject to the following conditions:
14+
15+
The above copyright notice and this permission notice shall be included in
16+
all copies or substantial portions of the Software.
17+
18+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
24+
THE SOFTWARE.

‎docs/topindex.html‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
{% extends "defindex.html" %}
2+
{% block tables %}
3+
<p><strong>Documentation for Micro Python and the pyboard:</strong></p>
4+
5+
<table class="contentstable" align="center"><tr>
6+
<td width="50%">
7+
<p class="biglink">
8+
<a class="biglink" href="{{ pathto("quickref") }}">Quick reference for the pyboard</a><br/>
9+
<span class="linkdescr">pinout for the pyboard and snippets of useful code</span>
10+
</p>
11+
<p class="biglink">
12+
<a class="biglink" href="{{ pathto("general") }}">General information about the pyboard</a><br/>
13+
<span class="linkdescr">read this first for a quick overview</span>
14+
</p>
15+
<p class="biglink">
16+
<a class="biglink" href="{{ pathto("tutorial/index") }}">Tutorials and code examples</a><br/>
17+
<span class="linkdescr">start here</span>
18+
</p>
19+
<p class="biglink">
20+
<a class="biglink" href="{{ pathto("library/index") }}">Library Reference</a><br/>
21+
<span class="linkdescr">Micro Python libraries, including the <a href="{{ pathto("library/pyb") }}">pyb module</a></span>
22+
</p>
23+
</td>
24+
<td width="50%">
25+
<p class="biglink">
26+
<a class="biglink" href="{{ pathto("hardware/index") }}">The pyboard hardware</a><br/>
27+
<span class="linkdescr">schematics, dimensions and component datasheets</span>
28+
</p>
29+
<p class="biglink">
30+
<a class="biglink" href="http://micropython.org/static/doc/Micro-Python-Windows-setup.pdf">Guide for pyboard on Windows (PDF)</a><br/>
31+
<span class="linkdescr">including DFU programming</span>
32+
</p>
33+
<p class="biglink">
34+
<a class="biglink" href="{{ pathto("license") }}">License</a><br/>
35+
<span class="linkdescr">Micro Python license information</span>
36+
</p>
37+
</td>
38+
</tr></table>
39+
40+
<p><strong>Indices and tables:</strong></p>
41+
<table class="contentstable" align="center"><tr>
42+
<td width="50%">
43+
<p class="biglink">
44+
<a class="biglink" href="{{ pathto("py-modindex") }}">Module index</a><br/>
45+
<span class="linkdescr">quick access to all modules</span>
46+
</p>
47+
<p class="biglink">
48+
<a class="biglink" href="{{ pathto("genindex") }}">Full index</a><br/>
49+
<span class="linkdescr">all functions, classes, constants</span>
50+
</p>
51+
</td><td width="50%">
52+
<p class="biglink">
53+
<a class="biglink" href="{{ pathto("contents") }}">Table of contents</a><br/>
54+
<span class="linkdescr">a list of all sections and subsections</span>
55+
</p>
56+
<p class="biglink">
57+
<a class="biglink" href="{{ pathto("search") }}">Search page</a><br/>
58+
<span class="linkdescr">search this documentation</span>
59+
</p>
60+
</td></tr>
61+
</table>
62+
63+
<p><strong>External links:</strong></p>
64+
65+
<table class="contentstable" align="center"><tr>
66+
<td width="50%">
67+
<p class="biglink">
68+
<a class="biglink" href="http://micropython.org">Micro Python homepage</a><br/>
69+
<span class="linkdescr">the official Micro Python site</span>
70+
</p>
71+
<p class="biglink">
72+
<a class="biglink" href="http://forum.micropython.org">Micro Python forum</a><br/>
73+
<span class="linkdescr">community discussion for all things related to Micro Python</span>
74+
</p>
75+
</td>
76+
<td width="50%">
77+
<p class="biglink">
78+
<a class="biglink" href="https://github.com/micropython">Micro Python on GitHub</a><br/>
79+
<span class="linkdescr">contribute to the source code on GitHub</span>
80+
</p>
81+
</td>
82+
</tr></table>
83+
84+
{% endblock %}

‎docs/tutorial/amp_skin.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -51,11 +51,11 @@ For example::
5151
dac.write_timed(buf, 400 * len(buf), mode=DAC.CIRCULAR)
5252

5353
You can also play WAV files using the Python ``wave`` module. You can get
54-
the wave module [here](/static/doc/examples/wave.py) and you will also need
55-
the chunk module available [here](/static/doc/examples/chunk.py). Put these
54+
the wave module `here <http://micropython.org/static/doc/examples/wave.py>`_ and you will also need
55+
the chunk module available `here <http://micropython.org/static/doc/examples/chunk.py>`_. Put these
5656
on your pyboard (either on the flash or the SD card in the top-level
5757
directory). You will need an 8-bit WAV file to play, such as
58-
[this one](/static/doc/examples/test.wav). Then you can do::
58+
`this one <http://micropython.org/static/doc/examples/test.wav>`_. Then you can do::
5959

6060
>>> import wave
6161
>>> from pyb import DAC

0 commit comments

Comments
 (0)