kopia lustrzana https://github.com/micropython/micropython
docs: Unify all the ports into one set of documentation.
With this commit there is now only one entry point into the whole documentation, which describes the general MicroPython language, and then from there there are links to information about specific platforms/ports. This commit doesn't change content (almost, it does fix a few internal links), it just reorganises things.pull/4194/merge
rodzic
5cc9517fc5
commit
b3e013f60e
52
docs/conf.py
52
docs/conf.py
|
@ -21,42 +21,21 @@ import os
|
||||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||||
sys.path.insert(0, os.path.abspath('.'))
|
sys.path.insert(0, os.path.abspath('.'))
|
||||||
|
|
||||||
# Work out the port to generate the docs for
|
|
||||||
from collections import OrderedDict
|
|
||||||
micropy_port = os.getenv('MICROPY_PORT') or 'pyboard'
|
|
||||||
tags.add('port_' + micropy_port)
|
|
||||||
ports = OrderedDict((
|
|
||||||
('unix', 'unix'),
|
|
||||||
('pyboard', 'the pyboard'),
|
|
||||||
('wipy', 'the WiPy'),
|
|
||||||
('esp8266', 'the ESP8266'),
|
|
||||||
))
|
|
||||||
|
|
||||||
# The members of the html_context dict are available inside topindex.html
|
# The members of the html_context dict are available inside topindex.html
|
||||||
micropy_version = os.getenv('MICROPY_VERSION') or 'latest'
|
micropy_version = os.getenv('MICROPY_VERSION') or 'latest'
|
||||||
micropy_all_versions = (os.getenv('MICROPY_ALL_VERSIONS') or 'latest').split(',')
|
micropy_all_versions = (os.getenv('MICROPY_ALL_VERSIONS') or 'latest').split(',')
|
||||||
url_pattern = '%s/en/%%s/%%s' % (os.getenv('MICROPY_URL_PREFIX') or '/',)
|
url_pattern = '%s/en/%%s' % (os.getenv('MICROPY_URL_PREFIX') or '/',)
|
||||||
html_context = {
|
html_context = {
|
||||||
'port':micropy_port,
|
'cur_version':micropy_version,
|
||||||
'port_name':ports[micropy_port],
|
|
||||||
'port_version':micropy_version,
|
|
||||||
'all_ports':[
|
|
||||||
(port_id, url_pattern % (micropy_version, port_id))
|
|
||||||
for port_id, port_name in ports.items()
|
|
||||||
],
|
|
||||||
'all_versions':[
|
'all_versions':[
|
||||||
(ver, url_pattern % (ver, micropy_port))
|
(ver, url_pattern % ver) for ver in micropy_all_versions
|
||||||
for ver in micropy_all_versions
|
|
||||||
],
|
],
|
||||||
'downloads':[
|
'downloads':[
|
||||||
('PDF', url_pattern % (micropy_version, 'micropython-%s.pdf' % micropy_port)),
|
('PDF', url_pattern % micropy_version + '/micropython-docs.pdf'),
|
||||||
],
|
],
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
# Specify a custom master document based on the port name
|
|
||||||
master_doc = micropy_port + '_' + 'index'
|
|
||||||
|
|
||||||
# -- General configuration ------------------------------------------------
|
# -- General configuration ------------------------------------------------
|
||||||
|
|
||||||
# If your documentation needs a minimal Sphinx version, state it here.
|
# If your documentation needs a minimal Sphinx version, state it here.
|
||||||
|
@ -86,7 +65,7 @@ source_suffix = '.rst'
|
||||||
#source_encoding = 'utf-8-sig'
|
#source_encoding = 'utf-8-sig'
|
||||||
|
|
||||||
# The master toctree document.
|
# The master toctree document.
|
||||||
#master_doc = 'index'
|
master_doc = 'index'
|
||||||
|
|
||||||
# General information about the project.
|
# General information about the project.
|
||||||
project = 'MicroPython'
|
project = 'MicroPython'
|
||||||
|
@ -323,24 +302,3 @@ texinfo_documents = [
|
||||||
|
|
||||||
# Example configuration for intersphinx: refer to the Python standard library.
|
# Example configuration for intersphinx: refer to the Python standard library.
|
||||||
intersphinx_mapping = {'python': ('http://docs.python.org/3.5', None)}
|
intersphinx_mapping = {'python': ('http://docs.python.org/3.5', None)}
|
||||||
|
|
||||||
# Append the other ports' specific folders/files to the exclude pattern
|
|
||||||
exclude_patterns.extend([port + '*' for port in ports if port != micropy_port])
|
|
||||||
|
|
||||||
modules_port_specific = {
|
|
||||||
'pyboard': ['pyb'],
|
|
||||||
'wipy': ['wipy'],
|
|
||||||
'esp8266': ['esp'],
|
|
||||||
}
|
|
||||||
|
|
||||||
modindex_exclude = []
|
|
||||||
|
|
||||||
for p, l in modules_port_specific.items():
|
|
||||||
if p != micropy_port:
|
|
||||||
modindex_exclude += l
|
|
||||||
|
|
||||||
# Exclude extra modules per port
|
|
||||||
modindex_exclude += {
|
|
||||||
'esp8266': ['cmath', 'select'],
|
|
||||||
'wipy': ['cmath'],
|
|
||||||
}.get(micropy_port, [])
|
|
||||||
|
|
|
@ -1,3 +1,5 @@
|
||||||
|
.. _esp8266_general:
|
||||||
|
|
||||||
General information about the ESP8266 port
|
General information about the ESP8266 port
|
||||||
==========================================
|
==========================================
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
.. _quickref:
|
.. _esp8266_quickref:
|
||||||
|
|
||||||
Quick reference for the ESP8266
|
Quick reference for the ESP8266
|
||||||
===============================
|
===============================
|
||||||
|
@ -9,6 +9,15 @@ Quick reference for the ESP8266
|
||||||
|
|
||||||
The Adafruit Feather HUZZAH board (image attribution: Adafruit).
|
The Adafruit Feather HUZZAH board (image attribution: Adafruit).
|
||||||
|
|
||||||
|
Below is a quick reference for ESP8266-based boards. If it is your first time
|
||||||
|
working with this board please consider reading the following sections first:
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
general.rst
|
||||||
|
tutorial/index.rst
|
||||||
|
|
||||||
Installing MicroPython
|
Installing MicroPython
|
||||||
----------------------
|
----------------------
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
.. _tutorial-index:
|
.. _esp8266_tutorial:
|
||||||
|
|
||||||
MicroPython tutorial for ESP8266
|
MicroPython tutorial for ESP8266
|
||||||
================================
|
================================
|
||||||
|
|
|
@ -1,12 +0,0 @@
|
||||||
MicroPython documentation and references
|
|
||||||
========================================
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
|
|
||||||
esp8266/quickref.rst
|
|
||||||
esp8266/general.rst
|
|
||||||
esp8266/tutorial/index.rst
|
|
||||||
library/index.rst
|
|
||||||
reference/index.rst
|
|
||||||
genrst/index.rst
|
|
||||||
license.rst
|
|
|
@ -3,10 +3,10 @@ MicroPython documentation and references
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
|
|
||||||
wipy/quickref.rst
|
|
||||||
wipy/general.rst
|
|
||||||
wipy/tutorial/index.rst
|
|
||||||
library/index.rst
|
library/index.rst
|
||||||
reference/index.rst
|
reference/index.rst
|
||||||
genrst/index.rst
|
genrst/index.rst
|
||||||
license.rst
|
license.rst
|
||||||
|
pyboard/quickref.rst
|
||||||
|
esp8266/quickref.rst
|
||||||
|
wipy/quickref.rst
|
|
@ -1,3 +1,5 @@
|
||||||
|
.. _pyboard_general:
|
||||||
|
|
||||||
General information about the pyboard
|
General information about the pyboard
|
||||||
=====================================
|
=====================================
|
||||||
|
|
||||||
|
@ -77,4 +79,6 @@ including setting up the serial prompt and downloading new firmware using
|
||||||
DFU programming:
|
DFU programming:
|
||||||
`PDF guide <http://micropython.org/resources/Micro-Python-Windows-setup.pdf>`__.
|
`PDF guide <http://micropython.org/resources/Micro-Python-Windows-setup.pdf>`__.
|
||||||
|
|
||||||
|
.. _hardware_index:
|
||||||
|
|
||||||
.. include:: hardware/index.rst
|
.. include:: hardware/index.rst
|
||||||
|
|
|
@ -1,5 +1,3 @@
|
||||||
.. _hardware_index:
|
|
||||||
|
|
||||||
The pyboard hardware
|
The pyboard hardware
|
||||||
--------------------
|
--------------------
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
.. _quickref:
|
.. _pyboard_quickref:
|
||||||
|
|
||||||
Quick reference for the pyboard
|
Quick reference for the pyboard
|
||||||
===============================
|
===============================
|
||||||
|
@ -20,6 +20,15 @@ or `PYBLITEv1.0 <http://micropython.org/resources/pyblitev10-pinout.jpg>`__.
|
||||||
.. image:: http://micropython.org/resources/pybv10-pinout-800px.jpg
|
.. image:: http://micropython.org/resources/pybv10-pinout-800px.jpg
|
||||||
:alt: PYBv1.0 pinout
|
:alt: PYBv1.0 pinout
|
||||||
|
|
||||||
|
Below is a quick reference for the pyboard. If it is your first time working with
|
||||||
|
this board please consider reading the following sections first:
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
general.rst
|
||||||
|
tutorial/index.rst
|
||||||
|
|
||||||
General board control
|
General board control
|
||||||
---------------------
|
---------------------
|
||||||
|
|
||||||
|
|
|
@ -26,7 +26,7 @@ For this tutorial, we will use the ``X1`` pin. Connect one end of the resistor t
|
||||||
|
|
||||||
Code
|
Code
|
||||||
----
|
----
|
||||||
By examining the :ref:`quickref`, we see that ``X1`` is connected to channel 1 of timer 5 (``TIM5 CH1``). Therefore we will first create a ``Timer`` object for timer 5, then create a ``TimerChannel`` object for channel 1::
|
By examining the :ref:`pyboard_quickref`, we see that ``X1`` is connected to channel 1 of timer 5 (``TIM5 CH1``). Therefore we will first create a ``Timer`` object for timer 5, then create a ``TimerChannel`` object for channel 1::
|
||||||
|
|
||||||
from pyb import Timer
|
from pyb import Timer
|
||||||
from time import sleep
|
from time import sleep
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
.. _tutorial-index:
|
.. _pyboard_tutorial:
|
||||||
|
|
||||||
MicroPython tutorial for the pyboard
|
MicroPython tutorial for the pyboard
|
||||||
====================================
|
====================================
|
||||||
|
|
|
@ -1,12 +0,0 @@
|
||||||
MicroPython documentation and references
|
|
||||||
========================================
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
|
|
||||||
pyboard/quickref.rst
|
|
||||||
pyboard/general.rst
|
|
||||||
pyboard/tutorial/index.rst
|
|
||||||
library/index.rst
|
|
||||||
reference/index.rst
|
|
||||||
genrst/index.rst
|
|
||||||
license.rst
|
|
|
@ -9,43 +9,20 @@
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
MicroPython runs on a variety of systems and each has their own specific
|
MicroPython runs on a variety of systems and hardware platforms. Here you can read
|
||||||
documentation. You are currently viewing the documentation for
|
the general documentation which applies to all systems, as well as specific information
|
||||||
<strong>{{ port_name }}</strong>.
|
about the various platforms -
|
||||||
|
also known as <a href="{{ pathto("reference/glossary") }}#term-micropython-port">ports</a>
|
||||||
|
- that MicroPython runs on.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<!--p>
|
<p><strong>General documentation for MicroPython:</strong></p>
|
||||||
Documentation for other systems are available:
|
|
||||||
{% for p in all_ports %}
|
|
||||||
<a href="{{ p[1] }}">{{ p[0] }}</a>{% if not loop.last %}, {% endif %}
|
|
||||||
{% endfor %}.
|
|
||||||
</p-->
|
|
||||||
|
|
||||||
<p><strong>Documentation for MicroPython and {{ port_name }}:</strong></p>
|
|
||||||
|
|
||||||
<table class="contentstable"><tr>
|
<table class="contentstable"><tr>
|
||||||
<td width="40%" style="padding-left:2em;">
|
<td width="40%" style="padding-left:2em;">
|
||||||
{% if port in ("pyboard", "wipy", "esp8266") %}
|
|
||||||
<p class="biglink">
|
|
||||||
<a class="biglink" href="{{ pathto(port + "/quickref") }}">Quick reference for {{ port_name }}</a><br/>
|
|
||||||
<span class="linkdescr">pinout for {{ port_name }} and snippets of useful code</span>
|
|
||||||
</p>
|
|
||||||
<p class="biglink">
|
|
||||||
<a class="biglink" href="{{ pathto(port + "/general") }}">General information about {{ port_name }}</a><br/>
|
|
||||||
<span class="linkdescr">read this first for a quick overview</span>
|
|
||||||
</p>
|
|
||||||
<p class="biglink">
|
|
||||||
<a class="biglink" href="{{ pathto(port + "/tutorial/index") }}">Tutorials and code examples</a><br/>
|
|
||||||
<span class="linkdescr">start here</span>
|
|
||||||
</p>
|
|
||||||
{% endif %}
|
|
||||||
<p class="biglink">
|
<p class="biglink">
|
||||||
<a class="biglink" href="{{ pathto("library/index") }}">Library Reference</a><br/>
|
<a class="biglink" href="{{ pathto("library/index") }}">Library Reference</a><br/>
|
||||||
{% if port == "pyboard" %}
|
<span class="linkdescr">MicroPython libraries and modules</span>
|
||||||
<span class="linkdescr">MicroPython libraries, including the <a href="{{ pathto("library/pyb") }}">pyb module</a></span>
|
|
||||||
{% else %}
|
|
||||||
<span class="linkdescr">MicroPython libraries, including the <a href="{{ pathto("library/machine") }}">machine module</a></span>
|
|
||||||
{% endif %}
|
|
||||||
</p>
|
</p>
|
||||||
<p class="biglink">
|
<p class="biglink">
|
||||||
<a class="biglink" href="{{ pathto("genrst/index") }}">MicroPython Differences</a><br/>
|
<a class="biglink" href="{{ pathto("genrst/index") }}">MicroPython Differences</a><br/>
|
||||||
|
@ -64,7 +41,27 @@
|
||||||
</td>
|
</td>
|
||||||
</tr></table>
|
</tr></table>
|
||||||
|
|
||||||
|
<p><strong>References and tutorials for specific platforms:</strong></p>
|
||||||
|
|
||||||
|
<table class="contentstable"><tr>
|
||||||
|
<td width="40%" style="padding-left:2em;">
|
||||||
|
<p class="biglink">
|
||||||
|
<a class="biglink" href="{{ pathto("pyboard/quickref") }}">Quick reference for the pyboard</a><br/>
|
||||||
|
<span class="linkdescr">pinout for the pyboard, snippets of useful code, and a tutorial</span>
|
||||||
|
</p>
|
||||||
|
<p class="biglink">
|
||||||
|
<a class="biglink" href="{{ pathto("esp8266/quickref") }}">Quick reference for the ESP8266</a><br/>
|
||||||
|
<span class="linkdescr">pinout for ESP8266-based boards, snippets of useful code, and a tutorial</span>
|
||||||
|
</p>
|
||||||
|
<p class="biglink">
|
||||||
|
<a class="biglink" href="{{ pathto("wipy/quickref") }}">Quick reference for the WiPy/CC3200</a><br/>
|
||||||
|
<span class="linkdescr">pinout for the WiPy/CC3200, snippets of useful code, and a tutorial</span>
|
||||||
|
</p>
|
||||||
|
</td>
|
||||||
|
</tr></table>
|
||||||
|
|
||||||
<p><strong>Indices and tables:</strong></p>
|
<p><strong>Indices and tables:</strong></p>
|
||||||
|
|
||||||
<table class="contentstable"><tr>
|
<table class="contentstable"><tr>
|
||||||
<td width="40%" style="padding-left:2em;">
|
<td width="40%" style="padding-left:2em;">
|
||||||
<p class="biglink">
|
<p class="biglink">
|
||||||
|
@ -82,7 +79,7 @@
|
||||||
<span class="linkdescr">MicroPython terms explained</span>
|
<span class="linkdescr">MicroPython terms explained</span>
|
||||||
</p>
|
</p>
|
||||||
<p class="biglink">
|
<p class="biglink">
|
||||||
<a class="biglink" href="{{ pathto(port + "_index") }}">Table of contents</a><br/>
|
<a class="biglink" href="{{ pathto("index") }}">Table of contents</a><br/>
|
||||||
<span class="linkdescr">a list of all sections and subsections</span>
|
<span class="linkdescr">a list of all sections and subsections</span>
|
||||||
</p>
|
</p>
|
||||||
</td></tr>
|
</td></tr>
|
||||||
|
|
|
@ -1,16 +1,10 @@
|
||||||
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
|
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
|
||||||
<span class="rst-current-version" data-toggle="rst-current-version">
|
<span class="rst-current-version" data-toggle="rst-current-version">
|
||||||
<span class="fa fa-book"> Ports and Versions</span>
|
<span class="fa fa-book"> Versions and Downloads</span>
|
||||||
{{ port }} ({{ port_version }})
|
{{ cur_version }}
|
||||||
<span class="fa fa-caret-down"></span>
|
<span class="fa fa-caret-down"></span>
|
||||||
</span>
|
</span>
|
||||||
<div class="rst-other-versions">
|
<div class="rst-other-versions">
|
||||||
<dl>
|
|
||||||
<dt>Ports</dt>
|
|
||||||
{% for slug, url in all_ports %}
|
|
||||||
<dd><a href="{{ url }}">{{ slug }}</a></dd>
|
|
||||||
{% endfor %}
|
|
||||||
</dl>
|
|
||||||
<dl>
|
<dl>
|
||||||
<dt>Versions</dt>
|
<dt>Versions</dt>
|
||||||
{% for slug, url in all_versions %}
|
{% for slug, url in all_versions %}
|
||||||
|
@ -27,7 +21,7 @@
|
||||||
<dl>
|
<dl>
|
||||||
<dt>External links</dt>
|
<dt>External links</dt>
|
||||||
<dd>
|
<dd>
|
||||||
<a href="http://www.micropython.org">micropython.org</a>
|
<a href="https://www.micropython.org">micropython.org</a>
|
||||||
</dd>
|
</dd>
|
||||||
<dd>
|
<dd>
|
||||||
<a href="https://github.com/micropython/micropython">GitHub</a>
|
<a href="https://github.com/micropython/micropython">GitHub</a>
|
||||||
|
|
|
@ -1,9 +0,0 @@
|
||||||
MicroPython documentation and references
|
|
||||||
========================================
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
|
|
||||||
library/index.rst
|
|
||||||
reference/index.rst
|
|
||||||
genrst/index.rst
|
|
||||||
license.rst
|
|
|
@ -1,3 +1,5 @@
|
||||||
|
.. _wipy_general:
|
||||||
|
|
||||||
General information about the WiPy
|
General information about the WiPy
|
||||||
==================================
|
==================================
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
.. _quickref_:
|
.. _wipy_quickref:
|
||||||
|
|
||||||
Quick reference for the WiPy
|
Quick reference for the WiPy
|
||||||
============================
|
============================
|
||||||
|
@ -7,6 +7,15 @@ Quick reference for the WiPy
|
||||||
:alt: WiPy pinout and alternate functions table
|
:alt: WiPy pinout and alternate functions table
|
||||||
:width: 800px
|
:width: 800px
|
||||||
|
|
||||||
|
Below is a quick reference for CC3200/WiPy. If it is your first time
|
||||||
|
working with this board please consider reading the following sections first:
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
general.rst
|
||||||
|
tutorial/index.rst
|
||||||
|
|
||||||
General board control (including sleep modes)
|
General board control (including sleep modes)
|
||||||
---------------------------------------------
|
---------------------------------------------
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
.. _wipy_tutorial_index:
|
.. _wipy_tutorial:
|
||||||
|
|
||||||
WiPy tutorials and examples
|
WiPy tutorials and examples
|
||||||
===========================
|
===========================
|
||||||
|
|
|
@ -23,7 +23,7 @@ As long as you take care of the hardware, you should be okay. It's almost
|
||||||
impossible to break the software on the WiPy, so feel free to play around
|
impossible to break the software on the WiPy, so feel free to play around
|
||||||
with writing code as much as you like. If the filesystem gets corrupt, see
|
with writing code as much as you like. If the filesystem gets corrupt, see
|
||||||
below on how to reset it. In the worst case you might need to do a safe boot,
|
below on how to reset it. In the worst case you might need to do a safe boot,
|
||||||
which is explained in detail :ref:`here <wipy_boot_modes>`.
|
which is explained in detail in :ref:`wipy_boot_modes`.
|
||||||
|
|
||||||
Plugging into the expansion board and powering on
|
Plugging into the expansion board and powering on
|
||||||
-------------------------------------------------
|
-------------------------------------------------
|
||||||
|
@ -32,13 +32,13 @@ The expansion board can power the WiPy via USB. The WiPy comes with a sticker
|
||||||
on top of the RF shield that labels all pins, and this should match the label
|
on top of the RF shield that labels all pins, and this should match the label
|
||||||
numbers on the expansion board headers. When plugging it in, the WiPy antenna
|
numbers on the expansion board headers. When plugging it in, the WiPy antenna
|
||||||
will end up on top of the SD card connector of the expansion board. A video
|
will end up on top of the SD card connector of the expansion board. A video
|
||||||
showing how to do this can be found `here <https://www.youtube.com/watch?v=47D9MZ9zFQw>`_.
|
showing how to do this can be found `here on YouTube <https://www.youtube.com/watch?v=47D9MZ9zFQw>`_.
|
||||||
|
|
||||||
Expansion board hardware guide
|
Expansion board hardware guide
|
||||||
------------------------------
|
------------------------------
|
||||||
|
|
||||||
The document explaining the hardware details of the expansion board can be found
|
The document explaining the hardware details of the expansion board can be found
|
||||||
`here <https://github.com/wipy/wipy/blob/master/docs/User_manual_exp_board.pdf>`_.
|
`in this PDF <https://github.com/wipy/wipy/blob/master/docs/User_manual_exp_board.pdf>`_.
|
||||||
|
|
||||||
Powering by an external power source
|
Powering by an external power source
|
||||||
------------------------------------
|
------------------------------------
|
||||||
|
|
Ładowanie…
Reference in New Issue