Skip to content

Commit cfcf47c

Browse files
author
Daniel Campora
committed
docs: Add initial draft documentation for the WiPy.
This makes all common files "port-aware" using the .. only directive.
1 parent b630de1 commit cfcf47c

33 files changed

+2230
-910
lines changed

‎README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,8 @@ preferably in a virtualenv:
121121

122122
In `micropython/docs`, build the docs:
123123

124-
make html
124+
make MICROPY_PORT=<port_name> BUILDDIR=<port_name>/build html
125125

126-
You'll find the index page at `micropython/docs/build/html/index.html`.
126+
Where ``<port_name>`` can be ``port_unix``, ``port_pyboard``, ``port_wipy`` or ``port_esp8266``.
127+
128+
You'll find the index page at `micropython/docs/<port_name>/build/html/index.html`.

‎docs/conf.py‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@
4747
#source_encoding = 'utf-8-sig'
4848

4949
# The master toctree document.
50-
master_doc = 'index'
50+
#master_doc = 'index'
5151

5252
# General information about the project.
5353
project = 'MicroPython'
@@ -297,3 +297,9 @@
297297
'port_name':ports[micropy_port],
298298
'all_ports':[(n, url_prefix + p) for p, n in ports.items()],
299299
}
300+
301+
# Append the other ports' specific folders/files to the exclude pattern
302+
exclude_patterns.extend([port + '*' for port in ports if port != micropy_port])
303+
304+
# Specify a custom master document based on the port name
305+
master_doc = micropy_port + '_' + 'index'

‎docs/contents.rst‎

Lines changed: 0 additions & 20 deletions
This file was deleted.

‎docs/esp8266_contents.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
MicroPython documentation contents
2+
==================================
3+
4+
.. toctree::
5+
6+
library/index.rst
7+
license.rst

‎docs/esp8266_index.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
MicroPython documentation and references
2+
========================================
3+
4+
.. toctree::
5+
6+
library/index.rst
7+
license.rst
8+
esp8266_contents.rst
9+
10+
Indices and tables
11+
==================
12+
13+
* :ref:`genindex`
14+
* :ref:`modindex`
15+
* :ref:`search`

‎docs/index.rst‎

Lines changed: 0 additions & 29 deletions
This file was deleted.

‎docs/library/index.rst‎

Lines changed: 77 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -17,17 +17,30 @@ The following standard Python libraries are built in to MicroPython.
1717
For additional libraries, please download them from the `micropython-lib repository
1818
<https://github.com/micropython/micropython-lib>`_.
1919

20-
.. toctree::
21-
:maxdepth: 1
20+
.. only:: port_pyboard
21+
22+
.. toctree::
23+
:maxdepth: 1
24+
25+
cmath.rst
26+
gc.rst
27+
math.rst
28+
os.rst
29+
select.rst
30+
struct.rst
31+
sys.rst
32+
time.rst
33+
34+
.. only:: port_wipy
2235

23-
cmath.rst
24-
gc.rst
25-
math.rst
26-
os.rst
27-
select.rst
28-
struct.rst
29-
sys.rst
30-
time.rst
36+
.. toctree::
37+
:maxdepth: 1
38+
39+
gc.rst
40+
os.rst
41+
select.rst
42+
sys.rst
43+
time.rst
3144

3245
Python micro-libraries
3346
----------------------
@@ -43,37 +56,68 @@ For example, ``import json`` will first search for a file ``json.py`` or
4356
directory ``json`` and load that package if it is found. If nothing is found,
4457
it will fallback to loading the built-in ``ujson`` module.
4558

46-
.. toctree::
47-
:maxdepth: 1
59+
.. only:: port_pyboard
4860

49-
ubinascii.rst
50-
uctypes.rst
51-
uhashlib.rst
52-
uheapq.rst
53-
ujson.rst
54-
ure.rst
55-
usocket.rst
56-
uzlib.rst
61+
.. toctree::
62+
:maxdepth: 1
63+
64+
ubinascii.rst
65+
uctypes.rst
66+
uhashlib.rst
67+
uheapq.rst
68+
ujson.rst
69+
ure.rst
70+
usocket.rst
71+
uzlib.rst
5772

58-
Libraries specific to the pyboard
59-
---------------------------------
73+
.. only:: port_pyboard
6074

61-
The following libraries are specific to the pyboard.
75+
Libraries specific to the pyboard
76+
---------------------------------
77+
78+
The following libraries are specific to the pyboard.
79+
80+
.. toctree::
81+
:maxdepth: 2
82+
83+
pyb.rst
84+
network.rst
6285

63-
.. toctree::
64-
:maxdepth: 2
86+
.. only:: port_wipy
87+
88+
.. toctree::
89+
:maxdepth: 1
90+
91+
ubinascii.rst
92+
uhashlib.rst
93+
uheapq.rst
94+
ujson.rst
95+
ure.rst
96+
usocket.rst
97+
98+
.. only:: port_wipy
99+
100+
Libraries specific to the WiPy
101+
---------------------------------
102+
103+
The following libraries are specific to the WiPy.
104+
105+
.. toctree::
106+
:maxdepth: 2
107+
108+
pyb.rst
109+
network.rst
65110

66-
pyb.rst
67-
network.rst
68111

69112
.. only:: port_esp8266
70113

71-
Libraries specific to the ESP8266
72-
---------------------------------
114+
Libraries specific to the ESP8266
115+
---------------------------------
73116

74-
The following libraries are specific to the ESP8266.
117+
The following libraries are specific to the ESP8266.
75118

76-
.. toctree::
77-
:maxdepth: 2
119+
.. toctree::
120+
:maxdepth: 2
78121

79-
esp.rst
122+
pyb.rst
123+
esp.rst

‎docs/library/micropython.rst‎

Lines changed: 19 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -7,23 +7,25 @@
77
Functions
88
---------
99

10-
.. function:: mem_info([verbose])
11-
12-
Print information about currently used memory. If the ``verbose`` argument
13-
is given then extra information is printed.
14-
15-
The information that is printed is implementation dependent, but currently
16-
includes the amount of stack and heap used. In verbose mode it prints out
17-
the entire heap indicating which blocks are used and which are free.
18-
19-
.. function:: qstr_info([verbose])
20-
21-
Print information about currently interned strings. If the ``verbose``
22-
argument is given then extra information is printed.
23-
24-
The information that is printed is implementation dependent, but currently
25-
includes the number of interned strings and the amount of RAM they use. In
26-
verbose mode it prints out the names of all RAM-interned strings.
10+
.. only:: port_pyboard or port_unix
11+
12+
.. function:: mem_info([verbose])
13+
14+
Print information about currently used memory. If the ``verbose`` argument
15+
is given then extra information is printed.
16+
17+
The information that is printed is implementation dependent, but currently
18+
includes the amount of stack and heap used. In verbose mode it prints out
19+
the entire heap indicating which blocks are used and which are free.
20+
21+
.. function:: qstr_info([verbose])
22+
23+
Print information about currently interned strings. If the ``verbose``
24+
argument is given then extra information is printed.
25+
26+
The information that is printed is implementation dependent, but currently
27+
includes the number of interned strings and the amount of RAM they use. In
28+
verbose mode it prints out the names of all RAM-interned strings.
2729

2830
.. function:: alloc_emergency_exception_buf(size)
2931

0 commit comments

Comments
 (0)