From 7ca1bd314bd5e3146f8c868f91af54d17dd04d45 Mon Sep 17 00:00:00 2001 From: Daniel Campora Date: Wed, 27 May 2015 13:59:59 +0200 Subject: [PATCH] docs: Generate a separate docs build for each port. Using Damien's approach where conf.py and topindex.html are shared by all ports. --- docs/conf.py | 22 ++++++- docs/contents.rst | 25 ++++--- docs/index.rst | 28 +++++--- docs/{ => pyboard}/general.rst | 0 docs/{ => pyboard}/hardware/index.rst | 0 docs/{ => pyboard}/quickref.rst | 0 docs/{ => pyboard}/tutorial/accel.rst | 0 docs/{ => pyboard}/tutorial/amp_skin.rst | 0 docs/{ => pyboard}/tutorial/assembler.rst | 0 docs/{ => pyboard}/tutorial/debounce.rst | 0 docs/{ => pyboard}/tutorial/fading_led.rst | 0 .../img/fading_leds_breadboard_fritzing.png | Bin .../tutorial/img/pyboard_servo.jpg | Bin .../tutorial/img/pyboard_usb_micro.jpg | Bin .../{ => pyboard}/tutorial/img/skin_amp_1.jpg | Bin .../{ => pyboard}/tutorial/img/skin_amp_2.jpg | Bin .../{ => pyboard}/tutorial/img/skin_lcd_1.jpg | Bin .../{ => pyboard}/tutorial/img/skin_lcd_2.jpg | Bin docs/{ => pyboard}/tutorial/index.rst | 0 docs/{ => pyboard}/tutorial/intro.rst | 0 docs/{ => pyboard}/tutorial/lcd_skin.rst | 0 docs/{ => pyboard}/tutorial/leds.rst | 0 docs/{ => pyboard}/tutorial/pass_through.rst | 0 docs/{ => pyboard}/tutorial/power_ctrl.rst | 0 docs/{ => pyboard}/tutorial/repl.rst | 0 docs/{ => pyboard}/tutorial/reset.rst | 0 docs/{ => pyboard}/tutorial/script.rst | 0 docs/{ => pyboard}/tutorial/servo.rst | 0 docs/{ => pyboard}/tutorial/switch.rst | 0 docs/{ => pyboard}/tutorial/timer.rst | 0 docs/{ => pyboard}/tutorial/usb_mouse.rst | 0 docs/topindex.html | 61 +++++++++++------- 32 files changed, 94 insertions(+), 42 deletions(-) rename docs/{ => pyboard}/general.rst (100%) rename docs/{ => pyboard}/hardware/index.rst (100%) rename docs/{ => pyboard}/quickref.rst (100%) rename docs/{ => pyboard}/tutorial/accel.rst (100%) rename docs/{ => pyboard}/tutorial/amp_skin.rst (100%) rename docs/{ => pyboard}/tutorial/assembler.rst (100%) rename docs/{ => pyboard}/tutorial/debounce.rst (100%) rename docs/{ => pyboard}/tutorial/fading_led.rst (100%) rename docs/{ => pyboard}/tutorial/img/fading_leds_breadboard_fritzing.png (100%) rename docs/{ => pyboard}/tutorial/img/pyboard_servo.jpg (100%) rename docs/{ => pyboard}/tutorial/img/pyboard_usb_micro.jpg (100%) rename docs/{ => pyboard}/tutorial/img/skin_amp_1.jpg (100%) rename docs/{ => pyboard}/tutorial/img/skin_amp_2.jpg (100%) rename docs/{ => pyboard}/tutorial/img/skin_lcd_1.jpg (100%) rename docs/{ => pyboard}/tutorial/img/skin_lcd_2.jpg (100%) rename docs/{ => pyboard}/tutorial/index.rst (100%) rename docs/{ => pyboard}/tutorial/intro.rst (100%) rename docs/{ => pyboard}/tutorial/lcd_skin.rst (100%) rename docs/{ => pyboard}/tutorial/leds.rst (100%) rename docs/{ => pyboard}/tutorial/pass_through.rst (100%) rename docs/{ => pyboard}/tutorial/power_ctrl.rst (100%) rename docs/{ => pyboard}/tutorial/repl.rst (100%) rename docs/{ => pyboard}/tutorial/reset.rst (100%) rename docs/{ => pyboard}/tutorial/script.rst (100%) rename docs/{ => pyboard}/tutorial/servo.rst (100%) rename docs/{ => pyboard}/tutorial/switch.rst (100%) rename docs/{ => pyboard}/tutorial/timer.rst (100%) rename docs/{ => pyboard}/tutorial/usb_mouse.rst (100%) diff --git a/docs/conf.py b/docs/conf.py index 5261bc5a4c..a3de50d81a 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -134,7 +134,7 @@ else: # The name of an image file (relative to this directory) to place at the top # of the sidebar. -#html_logo = '../logo/trans-logo.png' +#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 @@ -277,3 +277,23 @@ texinfo_documents = [ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'http://docs.python.org/': None} + + +# 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", "esp8266"), +)) + +# The members of the html_context dict are available inside topindex.html +url_prefix = os.getenv('MICROPY_URL_PREFIX') or '/' +html_context = { + 'port':micropy_port, + 'port_name':ports[micropy_port], + 'all_ports':[(n, url_prefix + p) for p, n in ports.items()], +} diff --git a/docs/contents.rst b/docs/contents.rst index e5d3ad3297..b35e80d85f 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -1,11 +1,20 @@ Micro Python documentation contents =================================== -.. toctree:: - - quickref.rst - general.rst - tutorial/index.rst - library/index.rst - hardware/index.rst - license.rst +.. only:: port_pyboard + + .. toctree:: + + pyboard/quickref.rst + pyboard/general.rst + pyboard/tutorial/index.rst + library/index.rst + pyboard/hardware/index.rst + license.rst + +.. only:: port_esp8266 + + .. toctree:: + + library/index.rst + license.rst diff --git a/docs/index.rst b/docs/index.rst index c11677efd5..e86ff857b7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,15 +1,25 @@ Micro Python documentation and references ========================================= -.. toctree:: - - quickref.rst - general.rst - tutorial/index.rst - library/index.rst - hardware/index.rst - license.rst - contents.rst +.. only:: port_pyboard + + .. toctree:: + + pyboard/quickref.rst + pyboard/general.rst + pyboard/tutorial/index.rst + library/index.rst + pyboard/hardware/index.rst + license.rst + contents.rst + +.. only:: port_esp8266 + + .. toctree:: + + library/index.rst + license.rst + contents.rst Indices and tables ================== diff --git a/docs/general.rst b/docs/pyboard/general.rst similarity index 100% rename from docs/general.rst rename to docs/pyboard/general.rst diff --git a/docs/hardware/index.rst b/docs/pyboard/hardware/index.rst similarity index 100% rename from docs/hardware/index.rst rename to docs/pyboard/hardware/index.rst diff --git a/docs/quickref.rst b/docs/pyboard/quickref.rst similarity index 100% rename from docs/quickref.rst rename to docs/pyboard/quickref.rst diff --git a/docs/tutorial/accel.rst b/docs/pyboard/tutorial/accel.rst similarity index 100% rename from docs/tutorial/accel.rst rename to docs/pyboard/tutorial/accel.rst diff --git a/docs/tutorial/amp_skin.rst b/docs/pyboard/tutorial/amp_skin.rst similarity index 100% rename from docs/tutorial/amp_skin.rst rename to docs/pyboard/tutorial/amp_skin.rst diff --git a/docs/tutorial/assembler.rst b/docs/pyboard/tutorial/assembler.rst similarity index 100% rename from docs/tutorial/assembler.rst rename to docs/pyboard/tutorial/assembler.rst diff --git a/docs/tutorial/debounce.rst b/docs/pyboard/tutorial/debounce.rst similarity index 100% rename from docs/tutorial/debounce.rst rename to docs/pyboard/tutorial/debounce.rst diff --git a/docs/tutorial/fading_led.rst b/docs/pyboard/tutorial/fading_led.rst similarity index 100% rename from docs/tutorial/fading_led.rst rename to docs/pyboard/tutorial/fading_led.rst diff --git a/docs/tutorial/img/fading_leds_breadboard_fritzing.png b/docs/pyboard/tutorial/img/fading_leds_breadboard_fritzing.png similarity index 100% rename from docs/tutorial/img/fading_leds_breadboard_fritzing.png rename to docs/pyboard/tutorial/img/fading_leds_breadboard_fritzing.png diff --git a/docs/tutorial/img/pyboard_servo.jpg b/docs/pyboard/tutorial/img/pyboard_servo.jpg similarity index 100% rename from docs/tutorial/img/pyboard_servo.jpg rename to docs/pyboard/tutorial/img/pyboard_servo.jpg diff --git a/docs/tutorial/img/pyboard_usb_micro.jpg b/docs/pyboard/tutorial/img/pyboard_usb_micro.jpg similarity index 100% rename from docs/tutorial/img/pyboard_usb_micro.jpg rename to docs/pyboard/tutorial/img/pyboard_usb_micro.jpg diff --git a/docs/tutorial/img/skin_amp_1.jpg b/docs/pyboard/tutorial/img/skin_amp_1.jpg similarity index 100% rename from docs/tutorial/img/skin_amp_1.jpg rename to docs/pyboard/tutorial/img/skin_amp_1.jpg diff --git a/docs/tutorial/img/skin_amp_2.jpg b/docs/pyboard/tutorial/img/skin_amp_2.jpg similarity index 100% rename from docs/tutorial/img/skin_amp_2.jpg rename to docs/pyboard/tutorial/img/skin_amp_2.jpg diff --git a/docs/tutorial/img/skin_lcd_1.jpg b/docs/pyboard/tutorial/img/skin_lcd_1.jpg similarity index 100% rename from docs/tutorial/img/skin_lcd_1.jpg rename to docs/pyboard/tutorial/img/skin_lcd_1.jpg diff --git a/docs/tutorial/img/skin_lcd_2.jpg b/docs/pyboard/tutorial/img/skin_lcd_2.jpg similarity index 100% rename from docs/tutorial/img/skin_lcd_2.jpg rename to docs/pyboard/tutorial/img/skin_lcd_2.jpg diff --git a/docs/tutorial/index.rst b/docs/pyboard/tutorial/index.rst similarity index 100% rename from docs/tutorial/index.rst rename to docs/pyboard/tutorial/index.rst diff --git a/docs/tutorial/intro.rst b/docs/pyboard/tutorial/intro.rst similarity index 100% rename from docs/tutorial/intro.rst rename to docs/pyboard/tutorial/intro.rst diff --git a/docs/tutorial/lcd_skin.rst b/docs/pyboard/tutorial/lcd_skin.rst similarity index 100% rename from docs/tutorial/lcd_skin.rst rename to docs/pyboard/tutorial/lcd_skin.rst diff --git a/docs/tutorial/leds.rst b/docs/pyboard/tutorial/leds.rst similarity index 100% rename from docs/tutorial/leds.rst rename to docs/pyboard/tutorial/leds.rst diff --git a/docs/tutorial/pass_through.rst b/docs/pyboard/tutorial/pass_through.rst similarity index 100% rename from docs/tutorial/pass_through.rst rename to docs/pyboard/tutorial/pass_through.rst diff --git a/docs/tutorial/power_ctrl.rst b/docs/pyboard/tutorial/power_ctrl.rst similarity index 100% rename from docs/tutorial/power_ctrl.rst rename to docs/pyboard/tutorial/power_ctrl.rst diff --git a/docs/tutorial/repl.rst b/docs/pyboard/tutorial/repl.rst similarity index 100% rename from docs/tutorial/repl.rst rename to docs/pyboard/tutorial/repl.rst diff --git a/docs/tutorial/reset.rst b/docs/pyboard/tutorial/reset.rst similarity index 100% rename from docs/tutorial/reset.rst rename to docs/pyboard/tutorial/reset.rst diff --git a/docs/tutorial/script.rst b/docs/pyboard/tutorial/script.rst similarity index 100% rename from docs/tutorial/script.rst rename to docs/pyboard/tutorial/script.rst diff --git a/docs/tutorial/servo.rst b/docs/pyboard/tutorial/servo.rst similarity index 100% rename from docs/tutorial/servo.rst rename to docs/pyboard/tutorial/servo.rst diff --git a/docs/tutorial/switch.rst b/docs/pyboard/tutorial/switch.rst similarity index 100% rename from docs/tutorial/switch.rst rename to docs/pyboard/tutorial/switch.rst diff --git a/docs/tutorial/timer.rst b/docs/pyboard/tutorial/timer.rst similarity index 100% rename from docs/tutorial/timer.rst rename to docs/pyboard/tutorial/timer.rst diff --git a/docs/tutorial/usb_mouse.rst b/docs/pyboard/tutorial/usb_mouse.rst similarity index 100% rename from docs/tutorial/usb_mouse.rst rename to docs/pyboard/tutorial/usb_mouse.rst diff --git a/docs/topindex.html b/docs/topindex.html index fb1e048d40..a810f61c4f 100644 --- a/docs/topindex.html +++ b/docs/topindex.html @@ -8,36 +8,53 @@ v{{ release|e }}{% if last_updated %}, {{ _('last updated') }} {{ last_updated|e }}{% endif %}.

+

+ MicroPython runs on a variety of systems and each has their own specific + documentation. You are currently viewing the documentation for + {{ port_name }}. +

+ + +

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 -

+ {% if port == "pyboard" %} +

+ 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
Micro Python libraries, including the pyb module

-

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

-

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

+ {% if port == "pyboard" %} +

+ The {{ port }} hardware
+ schematics, dimensions and component datasheets +

+

+ Guide for {{ port_name }} on Windows (PDF)
+ including DFU programming +

+ {% endif %}

License
Micro Python license information @@ -62,10 +79,6 @@ Table of contents
a list of all sections and subsections

-

- Search page
- search this documentation -