From 6ad1ce52395ddd517251ac57ad33d2d900312065 Mon Sep 17 00:00:00 2001
From: Ivan Kravets <me@ikravets.com>
Date: Tue, 20 Jun 2017 16:57:47 +0300
Subject: [PATCH] Improve docs for Platforms and Framworks

---
 docs                  |  2 +-
 scripts/docspregen.py | 40 +++++++++++++++++++++++-----------------
 2 files changed, 24 insertions(+), 18 deletions(-)

diff --git a/docs b/docs
index ac152877..00924a1e 160000
--- a/docs
+++ b/docs
@@ -1 +1 @@
-Subproject commit ac1528773f120a57df871ede64f71c13f20d6f90
+Subproject commit 00924a1ed8bfabbe48ce4445b5ccace19301e28e
diff --git a/scripts/docspregen.py b/scripts/docspregen.py
index 56453ada..d6a7c21f 100644
--- a/scripts/docspregen.py
+++ b/scripts/docspregen.py
@@ -176,21 +176,22 @@ def generate_platform(name):
     See the License for the specific language governing permissions and
     limitations under the License.
 """)
+    p = PlatformFactory.newPlatform(name)
 
-    lines.append(".. _platform_%s:" % name)
+    lines.append(".. _platform_%s:" % p.name)
     lines.append("")
 
-    _title = "Platform ``%s``" % name
-    lines.append(_title)
-    lines.append("=" * len(_title))
-
-    p = PlatformFactory.newPlatform(name)
+    lines.append(p.title)
+    lines.append("=" * len(p.title))
+    lines.append(":ref:`projectconf_env_platform` = ``%s``" % p.name)
+    lines.append("")
     lines.append(p.description)
     lines.append("""
 For more detailed information please visit `vendor site <%s>`_.""" %
                  p.vendor_url)
     lines.append("""
-.. contents::""")
+.. contents:: Contents
+    :local:""")
 
     #
     # Packages
@@ -286,15 +287,18 @@ def generate_framework(type_, data):
     lines.append(".. _framework_%s:" % type_)
     lines.append("")
 
-    _title = "Framework ``%s``" % type_
-    lines.append(_title)
-    lines.append("=" * len(_title))
+    lines.append(data['title'])
+    lines.append("=" * len(data['title']))
+    lines.append(":ref:`projectconf_env_framework` = ``%s``" % type_)
+    lines.append("")
     lines.append(data['description'])
     lines.append("""
 For more detailed information please visit `vendor site <%s>`_.
 """ % data['url'])
 
-    lines.append(".. contents::")
+    lines.append("""
+.. contents:: Contents
+    :local:""")
 
     lines.append("""
 Platforms
@@ -418,14 +422,16 @@ Rapid Embedded Development, Continuous and IDE integration in a few
 steps with PlatformIO thanks to built-in project generator for the most
 popular embedded boards and IDE.
 
-* You can list pre-configured boards using :ref:`cmd_boards` command or
-  `PlatformIO Boards Explorer <http://platformio.org/boards>`_
-* For more detailed ``board`` information please scroll tables below by
-  horizontal.
+.. note::
+    * You can list pre-configured boards by :ref:`cmd_boards` command or
+      `PlatformIO Boards Explorer <http://platformio.org/boards>`_
+    * For more detailed ``board`` information please scroll tables below by horizontal.
 """)
 
-    lines.append(".. contents::")
-    lines.append("")
+    lines.append("""
+.. contents:: Vendors
+    :local:
+    """)
 
     vendors = {}
     for data in BOARDS: