Add script for dynamically generating RST documents. Update platforms and frameworks documentation // Resolve 114

platformio/builder/scripts/frameworks/arduino.py

@@ -2,7 +2,11 @@
 # See LICENSE for details.
 
 """
-    Build script for Arduino Framework (based on Wiring).
+Arduino Framework allows writing cross-platform software to control
+devices attached to a wide range of Arduino boards to create all
+kinds of creative coding, interactive objects, spaces or physical experiences.
+
+http://arduino.cc/en/Reference/HomePage
 """
 
 from os import listdir, walk
@@ -146,7 +150,6 @@ if BOARD_BUILDOPTS.get("core", None) == "teensy":
 # Target: Build Core Library
 #
 
-
 libs = []
 
 if "variant" in BOARD_BUILDOPTS:

platformio/builder/scripts/frameworks/cmsis.py

@@ -2,7 +2,15 @@
 # See LICENSE for details.
 
 """
-    Build script for CMSIS Framework.
+The ARM Cortex Microcontroller Software Interface Standard (CMSIS) is a
+vendor-independent hardware abstraction layer for the Cortex-M processor
+series and specifies debugger interfaces. The CMSIS enables consistent and
+simple software interfaces to the processor for interface peripherals,
+real-time operating systems, and middleware. It simplifies software
+re-use, reducing the learning curve for new microcontroller developers
+and cutting the time-to-market for devices.
+
+http://www.arm.com/products/processors/cortex-m/cortex-microcontroller-software-interface-standard.php
 """
 
 from os.path import join

platformio/builder/scripts/frameworks/energia.py

@@ -2,7 +2,13 @@
 # See LICENSE for details.
 
 """
-    Build script for Energia Framework (based on Wiring).
+Energia framework enables pretty much anyone to start easily creating
+microcontroller-based projects and applications. Its easy-to-use libraries
+and functions provide developers of all experience levels to start
+blinking LEDs, buzzing buzzers and sensing sensors more quickly than ever
+before.
+
+http://energia.nu/reference/
 """
 
 from os.path import join

platformio/builder/scripts/frameworks/mbed.py

@@ -2,7 +2,15 @@
 # See LICENSE for details.
 
 """
-    Build script for Mbed Framework
+The mbed framework The mbed SDK has been designed to provide enough
+hardware abstraction to be intuitive and concise, yet powerful enough to
+build complex projects. It is built on the low-level ARM CMSIS APIs,
+allowing you to code down to the metal if needed. In addition to RTOS,
+USB and Networking libraries, a cookbook of hundreds of reusable
+peripheral and module libraries have been built on top of the SDK by
+the mbed Developer Community.
+
+http://mbed.org/
 """
 
 import xml.etree.ElementTree as ElementTree
@@ -123,17 +131,17 @@ for lib_path in eixdata.get("CPPPATH"):
 
 
 #
-# Target: Build MBED Library
+# Target: Build mbed Library
 #
 
 libs = [l for l in eixdata.get("STDLIBS", []) if l not in env.get("LIBS")]
 
 env.VariantDir(
-    join("$BUILD_DIR", "FrameworkMBED"),
+    join("$BUILD_DIR", "FrameworkMbed"),
     join("$PLATFORMFW_DIR", "core")
 )
 libs.append(env.Library(
-    join("$BUILD_DIR", "FrameworkMBED"),
+    join("$BUILD_DIR", "FrameworkMbed"),
     get_source_files(eixdata.get("FILES", []))
 ))
 

platformio/builder/scripts/frameworks/opencm3.py

@@ -2,7 +2,12 @@
 # See LICENSE for details.
 
 """
-    Build script for OpenCM3 Framework.
+The libopencm3 framework aims to create a free/libre/open-source
+firmware library for various ARM Cortex-M0(+)/M3/M4 microcontrollers,
+including ST STM32, Ti Tiva and Stellaris, NXP LPC 11xx, 13xx, 15xx,
+17xx parts, Atmel SAM3, Energy Micro EFM32 and others.
+
+http://www.libopencm3.org/wiki/Main_Page
 """
 
 import re

platformio/builder/scripts/frameworks/spl.py

@@ -2,7 +2,12 @@
 # See LICENSE for details.
 
 """
-    Build script for SPL Framework
+The ST Standard Peripheral Library provides a set of functions for
+handling the peripherals on the STM32 Cortex-M3 family.
+The idea is to save the user (the new user, in particular) having to deal
+directly with the registers.
+
+http://www.st.com/web/en/catalog/tools/FM147/CL1794/SC961/SS1743?sc=stm32embeddedsoftware
 """
 
 from os.path import join

platformio/builder/scripts/nxplpc.py

@@ -16,7 +16,7 @@ def UploadToDisk(target, source, env):  # pylint: disable=W0613,W0621
     env.AutodetectUploadPort()
     copyfile(join(env.subst("$BUILD_DIR"), "firmware.bin"),
              join(env.subst("$UPLOAD_PORT"), "firmware.bin"))
-    print ("Firmware has been successfully uploaded.\n" +
+    print ("Firmware has been successfully uploaded.\n"
            "Please restart your board.")
 
 env = DefaultEnvironment()

platformio/exception.py

@@ -44,6 +44,11 @@ class UnknownBoard(PlatformioException):
     MESSAGE = "Unknown board type '%s'"
 
 
+class UnknownFramework(PlatformioException):
+
+    MESSAGE = "Unknown framework '%s'"
+
+
 class UnknownPackage(PlatformioException):
 
     MESSAGE = "Detected unknown package '%s'"

platformio/platforms/atmelavr.py

@@ -8,8 +8,13 @@ from platformio.util import get_boards
 class AtmelavrPlatform(BasePlatform):
 
     """
-        An embedded platform for Atmel AVR microcontrollers
+    Atmel AVR 8- and 32-bit MCUs deliver a unique combination of
-        (with Arduino Framework)
+    performance, power efficiency and design flexibility. Optimized to
+    speed time to market-and easily adapt to new ones-they are based on
+    the industrys most code-efficient architecture for C and assembly
+    programming.
+
+    http://www.atmel.com/products/microcontrollers/avr/default.aspx
     """
 
     PACKAGES = {

platformio/platforms/atmelsam.py

@@ -7,8 +7,11 @@ from platformio.platforms.base import BasePlatform
 class AtmelsamPlatform(BasePlatform):
 
     """
-        An embedded platform for Atmel SAM microcontrollers
+    Atmel | SMART offers Flash- based ARM products based on the ARM
-        (with Arduino Framework)
+    Cortex-M0+, Cortex-M3 and Cortex-M4 architectures, ranging from 8KB
+    to 2MB of Flash including a rich peripheral and feature mix.
+
+    http://www.atmel.com/products/microcontrollers/arm/default.aspx
     """
 
     PACKAGES = {

platformio/platforms/base.py

@@ -12,6 +12,86 @@ from platformio import exception, util
 from platformio.app import get_state_item, set_state_item
 from platformio.pkgmanager import PackageManager
 
+PLATFORM_PACKAGES = {
+
+    "framework-arduinoavr": [
+        ("Arduino Wiring-based Framework (AVR Core, 1.6)",
+         "http://arduino.cc/en/Reference/HomePage")
+    ],
+    "framework-arduinosam": [
+        ("Arduino Wiring-based Framework (SAM Core, 1.6)",
+         "http://arduino.cc/en/Reference/HomePage")
+    ],
+    "framework-arduinoteensy": [
+        ("Arduino Wiring-based Framework",
+         "http://arduino.cc/en/Reference/HomePage")
+    ],
+    "framework-energiamsp430": [
+        ("Energia Wiring-based Framework (MSP430 Core)",
+         "http://energia.nu/reference/")
+    ],
+    "framework-energiativa": [
+        ("Energia Wiring-based Framework (LM4F Core)",
+         "http://energia.nu/reference/")
+    ],
+    "framework-cmsis": [
+        ("Vendor-independent hardware abstraction layer for the Cortex-M "
+         "processor series",
+         "http://www.arm.com/products/processors/"
+         "cortex-m/cortex-microcontroller-software-interface-standard.php")
+    ],
+    "framework-spl": [
+        ("Standard Peripheral Library for STM32 MCUs",
+         "http://www.st.com"
+         "/web/catalog/tools/FM147/CL1794/SC961/SS1743/PF257890")
+    ],
+    "framework-opencm3": [
+        ("libOpenCM3 Framework", "http://www.libopencm3.org/")
+    ],
+    "framework-mbed": [
+        ("mbed Framework", "http://mbed.org")
+    ],
+    "ldscripts": [
+        ("Linker Scripts",
+         "https://sourceware.org/binutils/docs/ld/Scripts.html")
+    ],
+    "toolchain-atmelavr": [
+        ("avr-gcc", "https://gcc.gnu.org/wiki/avr-gcc"),
+        ("GDB", "http://www.gnu.org/software/gdb/"),
+        ("AVaRICE", "http://avarice.sourceforge.net/"),
+        ("SimulAVR", "http://www.nongnu.org/simulavr/")
+    ],
+    "toolchain-gccarmnoneeabi": [
+        ("gcc-arm-embedded", "https://launchpad.net/gcc-arm-embedded"),
+        ("GDB", "http://www.gnu.org/software/gdb/")
+    ],
+    "toolchain-timsp430": [
+        ("msp-gcc", "http://sourceforge.net/projects/mspgcc/"),
+        ("GDB", "http://www.gnu.org/software/gdb/")
+    ],
+    "tool-avrdude": [
+        ("AVRDUDE", "http://www.nongnu.org/avrdude/")
+    ],
+    "tool-micronucleus": [
+        ("Micronucleus", "https://github.com/micronucleus/micronucleus")
+    ],
+    "tool-bossac": [
+        ("BOSSA CLI", "https://sourceforge.net/projects/b-o-s-s-a/")
+    ],
+    "tool-stlink": [
+        ("ST-Link", "https://github.com/texane/stlink")
+    ],
+    "tool-teensy": [
+        ("Teensy Loader", "https://www.pjrc.com/teensy/loader.html")
+    ],
+    "tool-lm4flash": [
+        ("Flash Programmer", "http://www.ti.com/tool/lmflashprogrammer")
+    ],
+    "tool-mspdebug": [
+        ("MSPDebug", "http://mspdebug.sourceforge.net/")
+    ]
+}
+
 
 class PlatformFactory(object):
 

platformio/platforms/freescalekinetis.py

@@ -7,7 +7,12 @@ from platformio.platforms.base import BasePlatform
 class FreescalekinetisPlatform(BasePlatform):
 
     """
-        An embedded platform for Freescale Kinetis series ARM microcontrollers
+    Freescale Kinetis Microcontrollers is family of multiple hardware- and
+    software-compatible ARM Cortex-M0+, Cortex-M4 and Cortex-M7-based MCU
+    series. Kinetis MCUs offer exceptional low-power performance,
+    scalability and feature integration.
+
+    http://www.freescale.com/webapp/sps/site/homepage.jsp?code=KINETIS
     """
 
     PACKAGES = {

platformio/platforms/nordicnrf51.py

@@ -7,7 +7,14 @@ from platformio.platforms.base import BasePlatform
 class Nordicnrf51Platform(BasePlatform):
 
     """
-        An embedded platform for Nordic nRF51 series ARM microcontrollers
+    The Nordic nRF51 Series is a family of highly flexible,
+    multi-protocol, system-on-chip (SoC) devices for ultra-low power
+    wireless applications. nRF51 Series devices support a range of
+    protocol stacks including Bluetooth Smart (previously called
+    Bluetooth low energy), ANT and proprietary 2.4GHz protocols such as
+    Gazell.
+
+    https://www.nordicsemi.com/eng/Products/nRF51-Series-SoC
     """
 
     PACKAGES = {

platformio/platforms/nxplpc.py

@@ -7,7 +7,14 @@ from platformio.platforms.base import BasePlatform
 class NxplpcPlatform(BasePlatform):
 
     """
-        An embedded platform for NXP LPC series ARM microcontrollers
+    The NXP LPC is a family of 32-bit microcontroller integrated circuits
+    by NXP Semiconductors. The LPC chips are grouped into related series
+    that are based around the same 32-bit ARM processor core, such as the
+    Cortex-M4F, Cortex-M3, Cortex-M0+, or Cortex-M0. Internally, each
+    microcontroller consists of the processor core, static RAM memory,
+    flash memory, debugging interface, and various peripherals.
+
+    http://www.nxp.com/products/microcontrollers/
     """
 
     PACKAGES = {

platformio/platforms/ststm32.py

@@ -7,7 +7,14 @@ from platformio.platforms.base import BasePlatform
 class Ststm32Platform(BasePlatform):
 
     """
-        An embedded platform for ST STM32 ARM microcontrollers
+    The STM32 family of 32-bit Flash MCUs based on the ARM Cortex-M
+    processor is designed to offer new degrees of freedom to MCU users.
+    It offers a 32-bit product range that combines very high performance,
+    real-time capabilities, digital signal processing, and low-power,
+    low-voltage operation, while maintaining full integration and ease of
+    development.
+
+    http://www.st.com/web/en/catalog/mmc/FM141/SC1169?sc=stm32
     """
 
     PACKAGES = {

platformio/platforms/teensy.py

@@ -8,8 +8,13 @@ from platformio.util import get_boards
 class TeensyPlatform(BasePlatform):
 
     """
-        An embedded platform for Teensy boards
+    Teensy is a complete USB-based microcontroller development system, in
-        (with Arduino Framework)
+    a very small footprint, capable of implementing many types of projects.
+    All programming is done via the USB port. No special programmer is
+    needed, only a standard "Mini-B" USB cable and a PC or Macintosh with
+    a USB port.
+
+    https://www.pjrc.com/teensy
     """
 
     PACKAGES = {

platformio/platforms/timsp430.py

@@ -5,9 +5,14 @@ from platformio.platforms.base import BasePlatform
 
 
 class Timsp430Platform(BasePlatform):
+
     """
-        An embedded platform for TI MSP430 microcontrollers
+    MSP430 microcontrollers (MCUs) from Texas Instruments (TI)
-        (with Energia Framework)
+    are 16-bit, RISC-based, mixed-signal processors designed for ultra-low
+    power. These MCUs offer the lowest power consumption and the perfect
+    mix of integrated peripherals for thousands of applications.
+
+    http://www.ti.com/lsds/ti/microcontrollers_16-bit_32-bit/msp/overview.page
     """
 
     PACKAGES = {

platformio/platforms/titiva.py

@@ -7,8 +7,12 @@ from platformio.platforms.base import BasePlatform
 class TitivaPlatform(BasePlatform):
 
     """
-        An embedded platform for TI TIVA C ARM microcontrollers
+    Texas Instruments TM4C12x MCUs offer the industrys most popular
-        (with Energia and OpenCM3 Frameworks)
+    ARM Cortex-M4 core with scalable memory and package options, unparalleled
+    connectivity peripherals, advanced application functions, industry-leading
+    analog integration, and extensive software solutions.
+
+    http://www.ti.com/lsds/ti/microcontrollers_16-bit_32-bit/c2000_performance/control_automation/tm4c12x/overview.page
     """
 
     PACKAGES = {

scripts/docspregen.py

@@ -0,0 +1,194 @@
+# Copyright (C) Ivan Kravets <me@ikravets.com>
+# See LICENSE for details.
+
+from os.path import dirname, join, realpath
+from sys import path
+from sys import exit as sys_exit
+from math import ceil
+path.append("..")
+from platformio import util
+from platformio.platforms.base import PLATFORM_PACKAGES, PlatformFactory
+
+
+def generate_boards(boards):
+
+    def _round_memory_size(size):
+        size = ceil(size)
+        for b in (64, 32, 16, 8, 4, 2, 1):
+            if b < size:
+                return int(ceil(size / b) * b)
+        assert NotImplemented()
+
+    lines = []
+
+    lines.append("""
+.. list-table::
+    :header-rows:  1
+
+    * - Type ``board``
+      - Name
+      - Microcontroller
+      - Frequency
+      - Flash
+      - RAM""")
+
+    for board in sorted(boards):
+        for type_, data in board.iteritems():
+            assert type_ in util.get_boards()
+            board_ram = float(data['upload']['maximum_ram_size']) / 1024
+            lines.append(
+                """
+    * - ``{type}``
+      - `{name} <{url}>`_
+      - {mcu}
+      - {f_cpu:d} MHz
+      - {rom} Kb
+      - {ram} Kb
+      """.format(
+                    type=type_,
+                    name=data['name'],
+                    url=data['url'],
+                    mcu=data['build']['mcu'].upper(),
+                    f_cpu=int((data['build']['f_cpu'][:-1])) / 1000000,
+                    ram=int(board_ram) if board_ram % 1 == 0 else board_ram,
+                    rom=_round_memory_size(
+                        data['upload']['maximum_size'] / 1024)
+                )
+            )
+
+    return "\n".join(lines)
+
+
+def generate_packages(packages):
+    lines = []
+    lines.append(""".. list-table::
+    :header-rows:  1
+
+    * - Name
+      - Contents""")
+    for type_, data in packages.iteritems():
+        assert type_ in PLATFORM_PACKAGES
+        contitems = [
+            "`%s <%s>`_" % (name, url)
+            for name, url in PLATFORM_PACKAGES[type_]
+        ]
+        lines.append("""
+    * - ``{type_}``
+      - {contents}""".format(
+            type_=type_,
+            contents=", ".join(contitems)))
+
+    lines.append("""
+.. warning::
+    **Linux Users:** Don't forget to install "udev" rules file
+    `99-platformio-udev.rules <https://github.com/ivankravets/platformio/blob/develop/scripts/99-platformio-udev.rules>`_ (an instruction is located in the file).
+
+""")
+    return "\n".join(lines)
+
+
+def generate_platform(name):
+    print "Processing platform: %s" % name
+    lines = []
+
+    lines.append(".. _platform_%s:" % name)
+    lines.append("")
+
+    _title = "Platform ``%s``" % name
+    lines.append(_title)
+    lines.append("=" * len(_title))
+
+    p = PlatformFactory.newPlatform(name)
+    lines.extend([l.strip() for l in p.__doc__.split("\n")])
+
+    lines.append(""".. contents::""")
+    lines.append("""
+Packages
+--------
+""")
+    lines.append(generate_packages(p.get_packages()))
+    lines.append("""
+Boards
+------
+
+.. note::
+    * You can list pre-configured boards by :ref:`cmd_boards` command
+    * For more detailed ``board`` information please scroll tables below by
+      horizontal.
+""")
+
+    vendors = {}
+    for board, data in util.get_boards().items():
+        platform = data['platform']
+        vendor = data['vendor']
+        if name in platform:
+            if vendor in vendors:
+                vendors[vendor].append({board: data})
+            else:
+                vendors[vendor] = [{board: data}]
+    for vendor, boards in sorted(vendors.iteritems()):
+        lines.append(str(vendor))
+        lines.append("~" * len(vendor))
+        lines.append(generate_boards(boards))
+    return "\n".join(lines)
+
+
+def update_platform_docs():
+    for name in PlatformFactory.get_platforms().keys():
+        rst_path = join(
+            dirname(realpath(__file__)), "..", "docs", "platforms", "%s.rst" % name)
+        with open(rst_path, "w") as f:
+            f.write(generate_platform(name))
+
+
+def generate_framework(name, data):
+    print "Processing framework: %s" % name
+    lines = []
+
+    lines.append(".. _framework_%s:" % name)
+    lines.append("")
+
+    _title = "Framework ``%s``" % name
+    lines.append(_title)
+    lines.append("=" * len(_title))
+    lines.append(data['description'])
+    lines.append("""\n.. contents::""")
+    lines.append("""
+Boards
+------
+
+.. note::
+    * You can list pre-configured boards by :ref:`cmd_boards` command
+    * For more detailed ``board`` information please scroll tables below by horizontal.
+""")
+
+    vendors = {}
+    for board, data in util.get_boards().items():
+        frameworks = data['frameworks']
+        vendor = data['vendor']
+        if name in frameworks:
+            if vendor in vendors:
+                vendors[vendor].append({board: data})
+            else:
+                vendors[vendor] = [{board: data}]
+    for vendor, boards in sorted(vendors.iteritems()):
+        lines.append(str(vendor))
+        lines.append("~" * len(vendor))
+        lines.append(generate_boards(boards))
+    return "\n".join(lines)
+
+
+def update_framework_docs():
+    for name, data in util.get_frameworks().items():
+        rst_path = join(util.get_source_dir(), "..", "docs", "frameworks",
+                        "%s.rst" % name)
+        with open(rst_path, "w") as f:
+            f.write(generate_framework(name, data))
+
+
+def main():
+    update_platform_docs()
+    update_framework_docs()
+
+if __name__ == "__main__":
+    sys_exit(main())