From b3e013f60ec0feb5b64bcadb45b154d093731c97 Mon Sep 17 00:00:00 2001 From: Damien George Date: Thu, 27 Sep 2018 17:27:57 +1000 Subject: 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. --- docs/conf.py | 52 +++---------------------------- docs/esp8266/general.rst | 2 ++ docs/esp8266/quickref.rst | 11 ++++++- docs/esp8266/tutorial/index.rst | 2 +- docs/esp8266_index.rst | 12 -------- docs/index.rst | 12 ++++++++ docs/pyboard/general.rst | 4 +++ docs/pyboard/hardware/index.rst | 2 -- docs/pyboard/quickref.rst | 11 ++++++- docs/pyboard/tutorial/fading_led.rst | 2 +- docs/pyboard/tutorial/index.rst | 2 +- docs/pyboard_index.rst | 12 -------- docs/templates/topindex.html | 59 +++++++++++++++++------------------- docs/templates/versions.html | 12 ++------ docs/unix_index.rst | 9 ------ docs/wipy/general.rst | 2 ++ docs/wipy/quickref.rst | 11 ++++++- docs/wipy/tutorial/index.rst | 2 +- docs/wipy/tutorial/intro.rst | 6 ++-- docs/wipy_index.rst | 12 -------- 20 files changed, 93 insertions(+), 144 deletions(-) delete mode 100644 docs/esp8266_index.rst create mode 100644 docs/index.rst delete mode 100644 docs/pyboard_index.rst delete mode 100644 docs/unix_index.rst delete mode 100644 docs/wipy_index.rst (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index bb8faea88..e85a68903 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -21,42 +21,21 @@ import os # documentation root, use os.path.abspath to make it absolute, like shown here. 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 micropy_version = os.getenv('MICROPY_VERSION') or 'latest' 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 = { - 'port':micropy_port, - '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() - ], + 'cur_version':micropy_version, 'all_versions':[ - (ver, url_pattern % (ver, micropy_port)) - for ver in micropy_all_versions + (ver, url_pattern % ver) for ver in micropy_all_versions ], '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 ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. @@ -86,7 +65,7 @@ source_suffix = '.rst' #source_encoding = 'utf-8-sig' # The master toctree document. -#master_doc = 'index' +master_doc = 'index' # General information about the project. project = 'MicroPython' @@ -323,24 +302,3 @@ texinfo_documents = [ # Example configuration for intersphinx: refer to the Python standard library. 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, []) diff --git a/docs/esp8266/general.rst b/docs/esp8266/general.rst index fe1cdc1c6..020e21df6 100644 --- a/docs/esp8266/general.rst +++ b/docs/esp8266/general.rst @@ -1,3 +1,5 @@ +.. _esp8266_general: + General information about the ESP8266 port ========================================== diff --git a/docs/esp8266/quickref.rst b/docs/esp8266/quickref.rst index c510e4064..95ae55b57 100644 --- a/docs/esp8266/quickref.rst +++ b/docs/esp8266/quickref.rst @@ -1,4 +1,4 @@ -.. _quickref: +.. _esp8266_quickref: Quick reference for the ESP8266 =============================== @@ -9,6 +9,15 @@ Quick reference for the ESP8266 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 ---------------------- diff --git a/docs/esp8266/tutorial/index.rst b/docs/esp8266/tutorial/index.rst index 39b459260..0a4b5f2a6 100644 --- a/docs/esp8266/tutorial/index.rst +++ b/docs/esp8266/tutorial/index.rst @@ -1,4 +1,4 @@ -.. _tutorial-index: +.. _esp8266_tutorial: MicroPython tutorial for ESP8266 ================================ diff --git a/docs/esp8266_index.rst b/docs/esp8266_index.rst deleted file mode 100644 index 519acecda..000000000 --- a/docs/esp8266_index.rst +++ /dev/null @@ -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 diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 000000000..af5ffb885 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,12 @@ +MicroPython documentation and references +======================================== + +.. toctree:: + + library/index.rst + reference/index.rst + genrst/index.rst + license.rst + pyboard/quickref.rst + esp8266/quickref.rst + wipy/quickref.rst diff --git a/docs/pyboard/general.rst b/docs/pyboard/general.rst index 97e9aabc0..0fc7332de 100644 --- a/docs/pyboard/general.rst +++ b/docs/pyboard/general.rst @@ -1,3 +1,5 @@ +.. _pyboard_general: + General information about the pyboard ===================================== @@ -77,4 +79,6 @@ including setting up the serial prompt and downloading new firmware using DFU programming: `PDF guide `__. +.. _hardware_index: + .. include:: hardware/index.rst diff --git a/docs/pyboard/hardware/index.rst b/docs/pyboard/hardware/index.rst index 91fea24e7..d6a14b2c5 100644 --- a/docs/pyboard/hardware/index.rst +++ b/docs/pyboard/hardware/index.rst @@ -1,5 +1,3 @@ -.. _hardware_index: - The pyboard hardware -------------------- diff --git a/docs/pyboard/quickref.rst b/docs/pyboard/quickref.rst index 87a7bba3e..ec789f2f0 100644 --- a/docs/pyboard/quickref.rst +++ b/docs/pyboard/quickref.rst @@ -1,4 +1,4 @@ -.. _quickref: +.. _pyboard_quickref: Quick reference for the pyboard =============================== @@ -20,6 +20,15 @@ or `PYBLITEv1.0 `__. .. image:: http://micropython.org/resources/pybv10-pinout-800px.jpg :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 --------------------- diff --git a/docs/pyboard/tutorial/fading_led.rst b/docs/pyboard/tutorial/fading_led.rst index 9f3f7c3ad..8303c9603 100644 --- a/docs/pyboard/tutorial/fading_led.rst +++ b/docs/pyboard/tutorial/fading_led.rst @@ -26,7 +26,7 @@ For this tutorial, we will use the ``X1`` pin. Connect one end of the resistor t 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 time import sleep diff --git a/docs/pyboard/tutorial/index.rst b/docs/pyboard/tutorial/index.rst index 1dc155f14..666c2de4f 100644 --- a/docs/pyboard/tutorial/index.rst +++ b/docs/pyboard/tutorial/index.rst @@ -1,4 +1,4 @@ -.. _tutorial-index: +.. _pyboard_tutorial: MicroPython tutorial for the pyboard ==================================== diff --git a/docs/pyboard_index.rst b/docs/pyboard_index.rst deleted file mode 100644 index 2255a7560..000000000 --- a/docs/pyboard_index.rst +++ /dev/null @@ -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 diff --git a/docs/templates/topindex.html b/docs/templates/topindex.html index 76e5e18d7..675fae29f 100644 --- a/docs/templates/topindex.html +++ b/docs/templates/topindex.html @@ -9,43 +9,20 @@

- MicroPython runs on a variety of systems and each has their own specific - documentation. You are currently viewing the documentation for - {{ port_name }}. + MicroPython runs on a variety of systems and hardware platforms. Here you can read + the general documentation which applies to all systems, as well as specific information + about the various platforms - + also known as ports + - that MicroPython runs on.

- - -

Documentation for MicroPython and {{ port_name }}:

+

General documentation for MicroPython:

- {% if port in ("pyboard", "wipy", "esp8266") %} -

- Quick reference for {{ port_name }}
- pinout for {{ port_name }} and snippets of useful code -

-

- General information about {{ port_name }}
- read this first for a quick overview -

-

- Tutorials and code examples
- start here -

- {% endif %}

Library Reference
- {% if port == "pyboard" %} - MicroPython libraries, including the pyb module - {% else %} - MicroPython libraries, including the machine module - {% endif %} + MicroPython libraries and modules

MicroPython Differences
@@ -64,7 +41,27 @@

+

References and tutorials for specific platforms:

+ + + +
+

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

+

+ Quick reference for the ESP8266
+ pinout for ESP8266-based boards, snippets of useful code, and a tutorial +

+

+ Quick reference for the WiPy/CC3200
+ pinout for the WiPy/CC3200, snippets of useful code, and a tutorial +

+
+

Indices and tables:

+ diff --git a/docs/templates/versions.html b/docs/templates/versions.html index 198630dd7..80b9b0f7d 100644 --- a/docs/templates/versions.html +++ b/docs/templates/versions.html @@ -1,16 +1,10 @@
- Ports and Versions - {{ port }} ({{ port_version }}) + Versions and Downloads + {{ cur_version }}
-
-
Ports
- {% for slug, url in all_ports %} -
{{ slug }}
- {% endfor %} -
Versions
{% for slug, url in all_versions %} @@ -27,7 +21,7 @@
External links
- micropython.org + micropython.org
GitHub diff --git a/docs/unix_index.rst b/docs/unix_index.rst deleted file mode 100644 index 1bfeb0bda..000000000 --- a/docs/unix_index.rst +++ /dev/null @@ -1,9 +0,0 @@ -MicroPython documentation and references -======================================== - -.. toctree:: - - library/index.rst - reference/index.rst - genrst/index.rst - license.rst diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst index f28edb4e4..aa195892b 100644 --- a/docs/wipy/general.rst +++ b/docs/wipy/general.rst @@ -1,3 +1,5 @@ +.. _wipy_general: + General information about the WiPy ================================== diff --git a/docs/wipy/quickref.rst b/docs/wipy/quickref.rst index cc3106002..9e13dfc2d 100644 --- a/docs/wipy/quickref.rst +++ b/docs/wipy/quickref.rst @@ -1,4 +1,4 @@ -.. _quickref_: +.. _wipy_quickref: Quick reference for the WiPy ============================ @@ -7,6 +7,15 @@ Quick reference for the WiPy :alt: WiPy pinout and alternate functions table :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) --------------------------------------------- diff --git a/docs/wipy/tutorial/index.rst b/docs/wipy/tutorial/index.rst index 816de27b5..e54887980 100644 --- a/docs/wipy/tutorial/index.rst +++ b/docs/wipy/tutorial/index.rst @@ -1,4 +1,4 @@ -.. _wipy_tutorial_index: +.. _wipy_tutorial: WiPy tutorials and examples =========================== diff --git a/docs/wipy/tutorial/intro.rst b/docs/wipy/tutorial/intro.rst index 3acc0510f..1b9049514 100644 --- a/docs/wipy/tutorial/intro.rst +++ b/docs/wipy/tutorial/intro.rst @@ -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 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, -which is explained in detail :ref:`here `. +which is explained in detail in :ref:`wipy_boot_modes`. 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 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 -showing how to do this can be found `here `_. +showing how to do this can be found `here on YouTube `_. Expansion board hardware guide ------------------------------ The document explaining the hardware details of the expansion board can be found -`here `_. +`in this PDF `_. Powering by an external power source ------------------------------------ diff --git a/docs/wipy_index.rst b/docs/wipy_index.rst deleted file mode 100644 index 15c04c0fb..000000000 --- a/docs/wipy_index.rst +++ /dev/null @@ -1,12 +0,0 @@ -MicroPython documentation and references -======================================== - -.. toctree:: - - wipy/quickref.rst - wipy/general.rst - wipy/tutorial/index.rst - library/index.rst - reference/index.rst - genrst/index.rst - license.rst -- cgit v1.2.3

@@ -82,7 +79,7 @@ MicroPython terms explained

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