Refactor dev/platforms and frameworks docs

platformio/exception.py

@@ -98,8 +98,8 @@ class UndefinedPackageVersion(PlatformioException):
 class PackageInstallError(PlatformioException):
 
     MESSAGE = ("Could not install '{0}' with version requirements '{1}' "
-               "for your system '{2}'.\n"
+               "for your system '{2}'.\n\n"
-               "More details: http://bit.ly/faq-package-manager")
+               "Please try this solution -> http://bit.ly/faq-package-manager")
 
 
 class FDUnrecognizedStatusCode(PlatformioException):

scripts/docspregen.py

@@ -12,7 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from math import ceil
 from os.path import dirname, isfile, join, realpath
 from sys import exit as sys_exit
 from sys import path
@@ -36,37 +35,42 @@ def is_compat_platform_and_framework(platform, framework):
     return False
 
 
-def generate_boards(boards, extend_debug=False):
+def campaign_url(url):
+    if "?" in url:
+        url += "&"
+    else:
+        url += "?"
+    return url + "utm_source=platformio&utm_medium=docs"
 
-    def _round_memory_size(size):
-        if size == 1:
-            return 1
-
-        size = ceil(size)
-        for b in (64, 32, 16, 8, 4, 2, 1):
-            if b < size:
-                return int(ceil(size / b) * b)
-        assert NotImplemented()
 
+def generate_boards(boards, extend_debug=False, skip_columns=None):
+    columns = [
+        ("ID", "``{id}``"),
+        ("Name", "`{name} <{url}>`_"),
+        ("Platform", ":ref:`{platform_title} <platform_{platform}>`"),
+        ("Debug", "{debug}"),
+        ("MCU", "{mcu}"),
+        ("Frequency", "{f_cpu:d} MHz"),
+        ("Flash", "{rom}"),
+        ("RAM", "{ram}"),
+    ]
     platforms = {m['name']: m['title'] for m in PLATFORM_MANIFESTS}
-
     lines = []
 
     lines.append("""
 .. list-table::
     :header-rows:  1
+""")
 
-    * - ID
+    # add header
-      - Name
+    for (name, template) in columns:
-      - Platform
+        if skip_columns and name in skip_columns:
-      - Debug
+            continue
-      - Microcontroller
+        prefix = "    * - " if name == "ID" else "      - "
-      - Frequency
+        lines.append(prefix + name)
-      - Flash
-      - RAM""")
 
     for data in sorted(boards, key=lambda item: item['id']):
-        debug = [":ref:`Yes <piodebug>`" if data['debug'] else ""]
+        debug = [":ref:`Yes <piodebug>`" if data['debug'] else "No"]
         if extend_debug and data['debug']:
             debug = []
             for name, options in data['debug']['tools'].items():
@@ -81,28 +85,74 @@ def generate_boards(boards, extend_debug=False):
                 else:
                     debug.append(tool)
 
-        board_ram = float(data['ram']) / 1024
+        variables = dict(
-        lines.append("""
-    * - ``{id}``
-      - `{name} <{url}>`_
-      - :ref:`{platform_title} <platform_{platform}>`
-      - {debug}
-      - {mcu}
-      - {f_cpu:d} MHz
-      - {rom} Kb
-      - {ram} Kb""".format(
             id=data['id'],
             name=data['name'],
             platform=data['platform'],
             platform_title=platforms[data['platform']],
             debug=", ".join(debug),
-            url=data['url'],
+            url=campaign_url(data['url']),
             mcu=data['mcu'].upper(),
             f_cpu=int(data['fcpu']) / 1000000,
-            ram=int(board_ram) if board_ram % 1 == 0 else board_ram,
+            ram=util.format_filesize(data['ram']),
-            rom=_round_memory_size(data['rom'] / 1024)))
+            rom=util.format_filesize(data['rom']))
 
-    return "\n".join(lines + [""])
+        for (name, template) in columns:
+            if skip_columns and name in skip_columns:
+                continue
+            prefix = "    * - " if name == "ID" else "      - "
+            lines.append(prefix + template.format(**variables))
+
+    if lines:
+        lines.append("")
+
+    return lines
+
+
+def generate_debug_boards(boards, skip_columns=None):
+    lines = []
+    onboard_debug = [
+        b for b in boards if b['debug'] and any(
+            t.get("onboard") for (_, t) in b['debug']['tools'].items())
+    ]
+    external_debug = [
+        b for b in boards if b['debug'] and b not in onboard_debug
+    ]
+    if onboard_debug or external_debug:
+        lines.append("""
+Debugging
+---------
+
+:ref:`piodebug` - "1-click" solution for debugging with a zero configuration.
+
+Supported debugging tools are listed in "Debug" column. For more detailed
+information, please scroll table by horizontal.
+You can switch between debugging :ref:`debugging_tools` using
+:ref:`projectconf_debug_tool` options.
+""")
+    if onboard_debug:
+        lines.append("""
+On-Board tools
+~~~~~~~~~~~~~~
+
+Boards listed below have on-board debugging tools and **ARE READY** for debugging!
+You do not need to use/buy external debugger.
+""")
+        lines.extend(
+            generate_boards(
+                onboard_debug, extend_debug=True, skip_columns=skip_columns))
+    if external_debug:
+        lines.append("""
+External tools
+~~~~~~~~~~~~~~
+
+Boards listed below are compatible with :ref:`piodebug` but depend on external
+debugging tools. See "Debug" column for compatible debugging tools.
+""")
+        lines.extend(
+            generate_boards(
+                external_debug, extend_debug=True, skip_columns=skip_columns))
+    return lines
 
 
 def generate_packages(platform, packagenames, is_embedded):
@@ -124,7 +174,7 @@ Packages
     * - `{name} <{url}>`__
       - {description}""".format(
             name=name,
-            url=API_PACKAGES[name]['url'],
+            url=campaign_url(API_PACKAGES[name]['url']),
             description=API_PACKAGES[name]['description']))
 
     if is_embedded:
@@ -160,8 +210,13 @@ Packages
     return "\n".join(lines)
 
 
-def generate_platform(name):
+def generate_platform(name, has_extra=False):
     print "Processing platform: %s" % name
+
+    compatible_boards = [
+        board for board in BOARDS if name in board['platform']
+    ]
+
     lines = []
 
     lines.append(
@@ -188,16 +243,45 @@ def generate_platform(name):
     lines.append(p.description)
     lines.append("""
 For more detailed information please visit `vendor site <%s>`_.""" %
-                 p.vendor_url)
+                 campaign_url(p.vendor_url))
     lines.append("""
 .. contents:: Contents
-    :local:""")
+    :local:
+    :depth: 1
+""")
+
+    #
+    # Extra
+    #
+    if has_extra:
+        lines.append(".. include:: %s_extra.rst" % p.name)
+
+    #
+    # Examples
+    #
+    lines.append("""
+Examples
+--------
+
+Examples are located in `%s development platform repository <%s>`_.
+""" % (p.title,
+       campaign_url(
+           "https://github.com/platformio/platform-%s/tree/develop/examples" %
+           p.name)))
+
+    #
+    # Debugging
+    #
+    if compatible_boards:
+        lines.extend(
+            generate_debug_boards(
+                compatible_boards, skip_columns=["Platform"]))
 
     #
     # Packages
     #
-    _packages_content = generate_packages(name,
+    _packages_content = generate_packages(name, p.packages.keys(),
-                                          p.packages.keys(), p.is_embedded())
+                                          p.is_embedded())
     if _packages_content:
         lines.append(_packages_content)
 
@@ -226,16 +310,13 @@ Frameworks
     #
     # Boards
     #
-    vendors = {}
+    if compatible_boards:
-    for board in BOARDS:
+        vendors = {}
-        vendor = board['vendor']
+        for board in compatible_boards:
-        if name in board['platform']:
+            if board['vendor'] not in vendors:
-            if vendor in vendors:
+                vendors[board['vendor']] = []
-                vendors[vendor].append(board)
+            vendors[board['vendor']].append(board)
-            else:
-                vendors[vendor] = [board]
 
-    if vendors:
         lines.append("""
 Boards
 ------
@@ -247,10 +328,10 @@ Boards
       horizontal.
 """)
 
-    for vendor, boards in sorted(vendors.iteritems()):
+        for vendor, boards in sorted(vendors.items()):
-        lines.append(str(vendor))
+            lines.append(str(vendor))
-        lines.append("~" * len(vendor))
+            lines.append("~" * len(vendor))
-        lines.append(generate_boards(boards))
+            lines.extend(generate_boards(boards, skip_columns=["Platform"]))
 
     return "\n".join(lines)
 
@@ -262,13 +343,24 @@ def update_platform_docs():
             dirname(realpath(__file__)), "..", "docs", "platforms")
         rst_path = join(platforms_dir, "%s.rst" % name)
         with open(rst_path, "w") as f:
-            f.write(generate_platform(name))
+            f.write(
-            if isfile(join(platforms_dir, "%s_extra.rst" % name)):
+                generate_platform(name,
-                f.write("\n.. include:: %s_extra.rst\n" % name)
+                                  isfile(
+                                      join(platforms_dir,
+                                           "%s_extra.rst" % name))))
 
 
-def generate_framework(type_, data):
+def generate_framework(type_, data, has_extra=False):
     print "Processing framework: %s" % type_
+
+    compatible_platforms = [
+        m for m in PLATFORM_MANIFESTS
+        if is_compat_platform_and_framework(m['name'], type_)
+    ]
+    compatible_boards = [
+        board for board in BOARDS if type_ in board['frameworks']
+    ]
+
     lines = []
 
     lines.append(
@@ -294,13 +386,38 @@ def generate_framework(type_, data):
     lines.append(data['description'])
     lines.append("""
 For more detailed information please visit `vendor site <%s>`_.
-""" % data['url'])
+""" % campaign_url(data['url']))
 
     lines.append("""
 .. contents:: Contents
-    :local:""")
+    :local:
+    :depth: 1""")
 
-    lines.append("""
+    # Extra
+    if has_extra:
+        lines.append(".. include:: %s_extra.rst" % type_)
+
+    #
+    # Debugging
+    #
+    if compatible_boards:
+        lines.extend(generate_debug_boards(compatible_boards))
+
+    if compatible_platforms:
+        # examples
+        lines.append("""
+Examples
+--------
+""")
+        for manifest in compatible_platforms:
+            lines.append("* `%s for %s <%s>`_" % (
+                data['title'], manifest['title'],
+                campaign_url(
+                    "https://github.com/platformio/platform-%s/tree/develop/examples"
+                    % manifest['name'])))
+
+        # Platforms
+        lines.append("""
 Platforms
 ---------
 .. list-table::
@@ -309,21 +426,23 @@ Platforms
     * - Name
       - Description""")
 
-    _found_platform = False
+        for manifest in compatible_platforms:
-    for manifest in PLATFORM_MANIFESTS:
+            p = PlatformFactory.newPlatform(manifest['name'])
-        if not is_compat_platform_and_framework(manifest['name'], type_):
+            lines.append("""
-            continue
-        _found_platform = True
-        p = PlatformFactory.newPlatform(manifest['name'])
-        lines.append(
-            """
     * - :ref:`platform_{type_}`
-      - {description}"""
+      - {description}""".format(
-            .format(type_=manifest['name'], description=p.description))
+                type_=manifest['name'], description=p.description))
-    if not _found_platform:
-        del lines[-1]
 
-    lines.append("""
+    #
+    # Boards
+    #
+    if compatible_boards:
+        vendors = {}
+        for board in compatible_boards:
+            if board['vendor'] not in vendors:
+                vendors[board['vendor']] = []
+            vendors[board['vendor']].append(board)
+        lines.append("""
 Boards
 ------
 
@@ -332,20 +451,10 @@ Boards
       `PlatformIO Boards Explorer <http://platformio.org/boards>`_
     * For more detailed ``board`` information please scroll tables below by horizontal.
 """)
-
+        for vendor, boards in sorted(vendors.items()):
-    vendors = {}
+            lines.append(str(vendor))
-    for data in BOARDS:
+            lines.append("~" * len(vendor))
-        frameworks = data['frameworks'] or []
+            lines.extend(generate_boards(boards))
-        vendor = data['vendor']
-        if type_ in frameworks:
-            if vendor in vendors:
-                vendors[vendor].append(data)
-            else:
-                vendors[vendor] = [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)
 
 
@@ -356,9 +465,11 @@ def update_framework_docs():
             dirname(realpath(__file__)), "..", "docs", "frameworks")
         rst_path = join(frameworks_dir, "%s.rst" % name)
         with open(rst_path, "w") as f:
-            f.write(generate_framework(name, framework))
+            f.write(
-            if isfile(join(frameworks_dir, "%s_extra.rst" % name)):
+                generate_framework(name, framework,
-                f.write("\n.. include:: %s_extra.rst\n" % name)
+                                   isfile(
+                                       join(frameworks_dir,
+                                            "%s_extra.rst" % name))))
 
 
 def update_create_platform_doc():
@@ -444,7 +555,7 @@ popular embedded boards and IDE.
     for vendor, boards in sorted(vendors.iteritems()):
         lines.append(str(vendor))
         lines.append("~" * len(vendor))
-        lines.append(generate_boards(boards))
+        lines.extend(generate_boards(boards))
 
     emboards_rst = join(
         dirname(realpath(__file__)), "..", "docs", "platforms",
@@ -484,11 +595,10 @@ Platforms
         if manifest['name'] not in platforms:
             continue
         p = PlatformFactory.newPlatform(manifest['name'])
-        lines.append(
+        lines.append("""
-            """
     * - :ref:`platform_{type_}`
-      - {description}"""
+      - {description}""".format(
-            .format(type_=manifest['name'], description=p.description))
+            type_=manifest['name'], description=p.description))
 
     # Frameworks
     lines.append("""
@@ -517,11 +627,11 @@ Boards
     for vendor, boards in sorted(vendors.iteritems()):
         lines.append(str(vendor))
         lines.append("~" * len(vendor))
-        lines.append(generate_boards(boards, extend_debug=True))
+        lines.extend(generate_boards(boards, extend_debug=True))
 
     with open(
-            join(util.get_source_dir(), "..", "docs", "plus",
+            join(util.get_source_dir(), "..", "docs", "plus", "debugging.rst"),
-                 "debugging.rst"), "r+") as fp:
+            "r+") as fp:
         content = fp.read()
         fp.seek(0)
         fp.truncate()