Enhance docs

docs/envvars.rst

@@ -18,10 +18,7 @@ General
 PlatformIO uses *General* environment variables for the common
 operations/commands.
 
-.. _envvar_CI:
+.. envvar:: CI
-
-CI
-~~
 
 PlatformIO handles ``CI`` variable which is setup by
 `Continuous Integration <http://en.wikipedia.org/wiki/Continuous_integration>`_
@@ -29,33 +26,21 @@ PlatformIO handles ``CI`` variable which is setup by
 Currently, PlatformIO uses it to disable prompts.
 
 In other words, ``CI=true`` automatically setup
-:ref:`PLATFORMIO_SETTING_ENABLE_PROMPTS=false <envvar_PLATFORMIO_SETTING_ENABLE_PROMPTS>`.
+:envvar:`PLATFORMIO_SETTING_ENABLE_PROMPTS=false <PLATFORMIO_SETTING_ENABLE_PROMPTS>`.
 
-.. _envvar_PLATFORMIO_HOME_DIR:
+.. envvar:: PLATFORMIO_HOME_DIR
-
-PLATFORMIO_HOME_DIR
-~~~~~~~~~~~~~~~~~~~
 
 Allows to override :ref:`projectconf` option :ref:`projectconf_pio_home_dir`.
 
-.. _envvar_PLATFORMIO_LIB_DIR:
+.. envvar:: PLATFORMIO_LIB_DIR
-
-PLATFORMIO_LIB_DIR
-~~~~~~~~~~~~~~~~~~
 
 Allows to override :ref:`projectconf` option :ref:`projectconf_pio_lib_dir`.
 
-.. _envvar_PLATFORMIO_SRC_DIR:
+.. envvar:: PLATFORMIO_SRC_DIR
-
-PLATFORMIO_SRC_DIR
-~~~~~~~~~~~~~~~~~~
 
 Allows to override :ref:`projectconf` option :ref:`projectconf_pio_src_dir`.
 
-.. _envvar_PLATFORMIO_ENVS_DIR:
+.. envvar:: PLATFORMIO_ENVS_DIR
-
-PLATFORMIO_ENVS_DIR
-~~~~~~~~~~~~~~~~~~~
 
 Allows to override :ref:`projectconf` option :ref:`projectconf_pio_envs_dir`.
 
@@ -63,74 +48,53 @@ Allows to override :ref:`projectconf` option :ref:`projectconf_pio_envs_dir`.
 Builder
 -------
 
-.. _envvar_PLATFORMIO_BUILD_FLAGS:
+.. envvar:: PLATFORMIO_BUILD_FLAGS
-
-PLATFORMIO_BUILD_FLAGS
-~~~~~~~~~~~~~~~~~~~~~~
 
 Allows to set :ref:`projectconf` option :ref:`projectconf_build_flags`.
 
-.. _envvar_PLATFORMIO_SRC_BUILD_FLAGS:
+.. envvar:: PLATFORMIO_SRC_BUILD_FLAGS
-
-PLATFORMIO_SRC_BUILD_FLAGS
-~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Allows to set :ref:`projectconf` option :ref:`projectconf_src_build_flags`.
 
-.. _envvar_PLATFORMIO_SRC_FILTER:
+.. envvar:: PLATFORMIO_SRC_FILTER
-
-PLATFORMIO_SRC_FILTER
-~~~~~~~~~~~~~~~~~~~~~
 
 Allows to set :ref:`projectconf` option :ref:`projectconf_src_filter`.
 
-.. _envvar_PLATFORMIO_EXTRA_SCRIPT:
+.. envvar:: PLATFORMIO_EXTRA_SCRIPT
-
-PLATFORMIO_EXTRA_SCRIPT
-~~~~~~~~~~~~~~~~~~~~~~~
 
 Allows to set :ref:`projectconf` option :ref:`projectconf_extra_script`.
 
+
 Settings
 --------
 
 Allows to override PlatformIO settings. You can manage them via
 :ref:`cmd_settings` command.
 
-
+.. envvar:: PLATFORMIO_SETTING_AUTO_UPDATE_LIBRARIES
-PLATFORMIO_SETTING_AUTO_UPDATE_LIBRARIES
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Allows to override setting :ref:`setting_auto_update_libraries`.
 
-PLATFORMIO_SETTING_AUTO_UPDATE_PLATFORMS
+.. envvar:: PLATFORMIO_SETTING_AUTO_UPDATE_PLATFORMS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Allows to override setting :ref:`setting_auto_update_platforms`.
 
-PLATFORMIO_SETTING_CHECK_LIBRARIES_INTERVAL
+.. envvar:: PLATFORMIO_SETTING_CHECK_LIBRARIES_INTERVAL
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Allows to override setting :ref:`setting_check_libraries_interval`.
 
-PLATFORMIO_SETTING_CHECK_PLATFORMIO_INTERVAL
+.. envvar:: PLATFORMIO_SETTING_CHECK_PLATFORMIO_INTERVAL
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Allows to override setting :ref:`setting_check_platformio_interval`.
 
-PLATFORMIO_SETTING_CHECK_PLATFORMS_INTERVAL
+.. envvar:: PLATFORMIO_SETTING_CHECK_PLATFORMS_INTERVAL
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Allows to override setting :ref:`setting_check_platforms_interval`.
 
-.. _envvar_PLATFORMIO_SETTING_ENABLE_PROMPTS:
+.. envvar:: PLATFORMIO_SETTING_ENABLE_PROMPTS
-
-PLATFORMIO_SETTING_ENABLE_PROMPTS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Allows to override setting :ref:`setting_enable_prompts`.
 
-PLATFORMIO_SETTING_ENABLE_TELEMETRY
+.. envvar:: PLATFORMIO_SETTING_ENABLE_TELEMETRY
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Allows to override setting :ref:`setting_enable_telemetry`.

docs/faq.rst

@@ -70,10 +70,10 @@ DISABLE** all prompts. It will allow you to avoid blocking.
 There are a few options:
 
 - using :option:`platformio --force` option before each command
-- using environment variable :ref:`PLATFORMIO_SETTING_ENABLE_PROMPTS=No <envvar_PLATFORMIO_SETTING_ENABLE_PROMPTS>`
+- using environment variable :envvar:`PLATFORMIO_SETTING_ENABLE_PROMPTS=No <PLATFORMIO_SETTING_ENABLE_PROMPTS>`
 - disable global setting ``enable_prompts`` via :ref:`cmd_settings` command
 - masking under Continuous Integration system via environment variable
-  :ref:`CI=true <envvar_CI>`.
+  :envvar:`CI=true <CI>`.
 
 
 Windows: ``UnicodeDecodeError: 'ascii' codec can't decode byte``

docs/index.rst

@@ -19,7 +19,7 @@ libOpenCM3, etc.*
   `Issues <https://github.com/platformio/platformio/issues>`_
 * `Blog <http://www.ikravets.com/category/computer-life/platformio>`_ |
   `Reddit <http://www.reddit.com/r/platformio/>`_ |
-  `Facebook <https://www.facebook.com/platformio>`_ |  
+  `Facebook <https://www.facebook.com/platformio>`_ |
   `Twitter <https://twitter.com/PlatformIO_Org>`_
 
 You have **no need** to install any *IDE* or compile any tool chains. *PlatformIO*
@@ -61,18 +61,39 @@ Contents
 --------
 
 .. toctree::
+    :caption: Getting Started
     :maxdepth: 2
 
-    quickstart
     installation
+    quickstart
+    userguide/index
+
+.. toctree::
+    :caption: Configuration
+    :maxdepth: 2
+
     projectconf
     envvars
+
+.. toctree::
+    :caption: Instruments
+    :maxdepth: 2
+
     Platforms & Boards <platforms/index>
     frameworks/index
+
+.. toctree::
+    :caption: Integration
+    :maxdepth: 2
+
     librarymanager/index
-    userguide/index
     ci/index
     ide
+
+.. toctree::
+    :caption: Miscellaneous
+    :maxdepth: 2
+
     articles
     FAQ <faq>
     history

docs/projectconf.rst

@@ -42,7 +42,7 @@ A default value is User's home directory:
 * Windows ``%HOMEPATH%\.platformio``
 
 This option can be overridden by global environment variable
-:ref:`envvar_PLATFORMIO_HOME_DIR`.
+:envvar:`PLATFORMIO_HOME_DIR`.
 
 .. _projectconf_pio_lib_dir:
 
@@ -55,7 +55,7 @@ This directory is used to store external libraries downloaded by
 A default value is ``%home_dir%/lib``.
 
 This option can be overridden by global environment variable
-:ref:`envvar_PLATFORMIO_LIB_DIR`.
+:envvar:`PLATFORMIO_LIB_DIR`.
 
 .. note::
     You can put here your own/private libraries. The source code of each
@@ -73,7 +73,7 @@ command.
 A default value is ``%project_dir%/src``.
 
 This option can be overridden by global environment variable
-:ref:`envvar_PLATFORMIO_SRC_DIR`.
+:envvar:`PLATFORMIO_SRC_DIR`.
 
 .. note::
     This option is useful for people who migrate from Arduino/Energia IDEs where
@@ -97,7 +97,7 @@ next build operation.
 A default value is ``%project_dir%/.pioenvs``.
 
 This option can be overridden by global environment variable
-:ref:`envvar_PLATFORMIO_ENVS_DIR`.
+:envvar:`PLATFORMIO_ENVS_DIR`.
 
 .. note::
     If you have any problems with building your Project environmets which
@@ -267,7 +267,7 @@ processes:
         ``-l``.
 
 This option can be set by global environment variable
-:ref:`envvar_PLATFORMIO_BUILD_FLAGS`.
+:envvar:`PLATFORMIO_BUILD_FLAGS`.
 
 Example:
 
@@ -309,7 +309,7 @@ but will be applied only for the project source code from
 :ref:`projectconf_pio_src_dir` directory.
 
 This option can be set by global environment variable
-:ref:`envvar_PLATFORMIO_SRC_BUILD_FLAGS`.
+:envvar:`PLATFORMIO_SRC_BUILD_FLAGS`.
 
 .. _projectconf_src_filter:
 
@@ -331,7 +331,7 @@ By default, ``src_filter`` is predefined to
 exclude ``.git`` and ``svn`` repository folders and exclude ``examples`` folder.
 
 This option can be set by global environment variable
-:ref:`envvar_PLATFORMIO_SRC_FILTER`.
+:envvar:`PLATFORMIO_SRC_FILTER`.
 
 ``lib_install``
 ^^^^^^^^^^^^^^^
@@ -404,7 +404,7 @@ section of
 `SCons documentation <http://www.scons.org/doc/production/HTML/scons-user.html#chap-environments>`_.
 
 This option can be set by global environment variable
-:ref:`envvar_PLATFORMIO_EXTRA_SCRIPT`.
+:envvar:`PLATFORMIO_EXTRA_SCRIPT`.
 
 Example, specify own upload command for :ref:`platform_atmelavr`: