From 35f7d8a4cc80a0f928988eeddb20565e14326fb6 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Fri, 14 Aug 2015 00:14:04 +0300 Subject: [PATCH] Enhance docs --- docs/envvars.rst | 72 +++++++++++--------------------------------- docs/faq.rst | 4 +-- docs/index.rst | 27 +++++++++++++++-- docs/projectconf.rst | 16 +++++----- 4 files changed, 52 insertions(+), 67 deletions(-) diff --git a/docs/envvars.rst b/docs/envvars.rst index 383322f3..8682e51d 100644 --- a/docs/envvars.rst +++ b/docs/envvars.rst @@ -18,10 +18,7 @@ General PlatformIO uses *General* environment variables for the common operations/commands. -.. _envvar_CI: - -CI -~~ +.. envvar:: CI PlatformIO handles ``CI`` variable which is setup by `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=false `. -.. _envvar_PLATFORMIO_HOME_DIR: - -PLATFORMIO_HOME_DIR -~~~~~~~~~~~~~~~~~~~ +.. envvar:: PLATFORMIO_HOME_DIR Allows to override :ref:`projectconf` option :ref:`projectconf_pio_home_dir`. -.. _envvar_PLATFORMIO_LIB_DIR: - -PLATFORMIO_LIB_DIR -~~~~~~~~~~~~~~~~~~ +.. envvar:: PLATFORMIO_LIB_DIR Allows to override :ref:`projectconf` option :ref:`projectconf_pio_lib_dir`. -.. _envvar_PLATFORMIO_SRC_DIR: - -PLATFORMIO_SRC_DIR -~~~~~~~~~~~~~~~~~~ +.. envvar:: PLATFORMIO_SRC_DIR Allows to override :ref:`projectconf` option :ref:`projectconf_pio_src_dir`. -.. _envvar_PLATFORMIO_ENVS_DIR: - -PLATFORMIO_ENVS_DIR -~~~~~~~~~~~~~~~~~~~ +.. envvar:: 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: - -PLATFORMIO_BUILD_FLAGS -~~~~~~~~~~~~~~~~~~~~~~ +.. envvar:: PLATFORMIO_BUILD_FLAGS Allows to set :ref:`projectconf` option :ref:`projectconf_build_flags`. -.. _envvar_PLATFORMIO_SRC_BUILD_FLAGS: - -PLATFORMIO_SRC_BUILD_FLAGS -~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. envvar:: PLATFORMIO_SRC_BUILD_FLAGS Allows to set :ref:`projectconf` option :ref:`projectconf_src_build_flags`. -.. _envvar_PLATFORMIO_SRC_FILTER: - -PLATFORMIO_SRC_FILTER -~~~~~~~~~~~~~~~~~~~~~ +.. envvar:: PLATFORMIO_SRC_FILTER Allows to set :ref:`projectconf` option :ref:`projectconf_src_filter`. -.. _envvar_PLATFORMIO_EXTRA_SCRIPT: - -PLATFORMIO_EXTRA_SCRIPT -~~~~~~~~~~~~~~~~~~~~~~~ +.. envvar:: 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. - -PLATFORMIO_SETTING_AUTO_UPDATE_LIBRARIES -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. envvar:: 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: - -PLATFORMIO_SETTING_ENABLE_PROMPTS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. envvar:: 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`. diff --git a/docs/faq.rst b/docs/faq.rst index 59e8d400..f103986b 100644 --- a/docs/faq.rst +++ b/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 ` +- using environment variable :envvar:`PLATFORMIO_SETTING_ENABLE_PROMPTS=No ` - disable global setting ``enable_prompts`` via :ref:`cmd_settings` command - masking under Continuous Integration system via environment variable - :ref:`CI=true `. + :envvar:`CI=true `. Windows: ``UnicodeDecodeError: 'ascii' codec can't decode byte`` diff --git a/docs/index.rst b/docs/index.rst index 25ef8d5c..0b300b73 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,7 +19,7 @@ libOpenCM3, etc.* `Issues `_ * `Blog `_ | `Reddit `_ | - `Facebook `_ | + `Facebook `_ | `Twitter `_ 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 frameworks/index + +.. toctree:: + :caption: Integration + :maxdepth: 2 + librarymanager/index - userguide/index ci/index ide + +.. toctree:: + :caption: Miscellaneous + :maxdepth: 2 + articles FAQ history diff --git a/docs/projectconf.rst b/docs/projectconf.rst index 53656704..a3641e5c 100644 --- a/docs/projectconf.rst +++ b/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 `_. 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`: