From 849a49f665b10a223fe83f1c75cb900230462925 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Sat, 6 Sep 2014 13:44:45 +0300 Subject: [PATCH] Add Library Manager documentation --- docs/index.rst | 1 + docs/librarymanager/config.rst | 12 +++ docs/librarymanager/index.rst | 11 +++ docs/userguide/index.rst | 1 + docs/userguide/lib/cmd_install.rst | 68 ++++++++++++++ docs/userguide/lib/cmd_list.rst | 31 ++++++ docs/userguide/lib/cmd_search.rst | 136 +++++++++++++++++++++++++++ docs/userguide/lib/cmd_show.rst | 34 +++++++ docs/userguide/lib/cmd_uninstall.rst | 31 ++++++ docs/userguide/lib/cmd_update.rst | 33 +++++++ docs/userguide/lib/index.rst | 22 +++++ 11 files changed, 380 insertions(+) create mode 100644 docs/librarymanager/config.rst create mode 100644 docs/librarymanager/index.rst create mode 100644 docs/userguide/lib/cmd_install.rst create mode 100644 docs/userguide/lib/cmd_list.rst create mode 100644 docs/userguide/lib/cmd_search.rst create mode 100644 docs/userguide/lib/cmd_show.rst create mode 100644 docs/userguide/lib/cmd_uninstall.rst create mode 100644 docs/userguide/lib/cmd_update.rst create mode 100644 docs/userguide/lib/index.rst diff --git a/docs/index.rst b/docs/index.rst index d082ae73..be90e815 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -42,6 +42,7 @@ Contents installation projectconf platforms/index + librarymanager/index userguide/index ide history diff --git a/docs/librarymanager/config.rst b/docs/librarymanager/config.rst new file mode 100644 index 00000000..dd565f76 --- /dev/null +++ b/docs/librarymanager/config.rst @@ -0,0 +1,12 @@ +.. _library_config: + +library.json +============ + +Library Configuration File + +.. warning:: + The filling of this page is currently in progress... + + For more detailed information please go to + `GitHub Issue #6 `_. diff --git a/docs/librarymanager/index.rst b/docs/librarymanager/index.rst new file mode 100644 index 00000000..d17de1f7 --- /dev/null +++ b/docs/librarymanager/index.rst @@ -0,0 +1,11 @@ +.. _librarymanager: + +Library Manager +=============== + + +.. toctree:: + :maxdepth: 2 + + config + User Guide <../userguide/lib/index> diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst index 5779209a..3cadb2f5 100644 --- a/docs/userguide/index.rst +++ b/docs/userguide/index.rst @@ -16,6 +16,7 @@ To print all available commands and options use: cmd_init cmd_install + platformio lib cmd_list cmd_run cmd_search diff --git a/docs/userguide/lib/cmd_install.rst b/docs/userguide/lib/cmd_install.rst new file mode 100644 index 00000000..81483ff5 --- /dev/null +++ b/docs/userguide/lib/cmd_install.rst @@ -0,0 +1,68 @@ +.. _cmd_lib_install: + +platformio lib install +====================== + +.. contents:: + +Usage +----- + +.. code-block:: bash + + platformio lib install [OPTIONS] [NAMES] + + +Description +----------- + +Install new library + +Options +------- + +.. option:: + -v, --version + +Install specified version of library + + +Examples +-------- + +1. Install the latest version of library + +.. code-block:: bash + + $ platformio lib install Arduino-IRremote + Installing Arduino-IRremote library: + Downloading [####################################] 100% + Unpacking [####################################] 100% + The library 'Arduino-IRremote' has been successfully installed! + + +2. Install specified version of library + +.. code-block:: bash + + $ platformio lib install Arduino-XBee --version=0.5 + Installing Arduino-XBee library: + Downloading [####################################] 100% + Unpacking [####################################] 100% + The library 'Arduino-XBee' has been successfully installed! + + +3. Install library with dependencies + +.. code-block:: bash + + $ platformio lib install Adafruit-Arduino-ST7735 + Installing Adafruit-Arduino-ST7735 library: + Downloading [####################################] 100% + Unpacking [####################################] 100% + The library 'Adafruit-Arduino-ST7735' has been successfully installed! + Installing dependencies: + Installing Adafruit-Arduino-GFX library: + Downloading [####################################] 100% + Unpacking [####################################] 100% + The library 'Adafruit-Arduino-GFX' has been successfully installed! diff --git a/docs/userguide/lib/cmd_list.rst b/docs/userguide/lib/cmd_list.rst new file mode 100644 index 00000000..757bc7de --- /dev/null +++ b/docs/userguide/lib/cmd_list.rst @@ -0,0 +1,31 @@ +.. _cmd_lib_list: + +platformio lib list +=================== + +.. contents:: + +Usage +----- + +.. code-block:: bash + + platformio lib list + + +Description +----------- + +List installed libraries + + +Examples +-------- + +.. code-block:: bash + + $ platformio lib list + Arduino-IRremote Send and receive infrared signals with multiple protocols + ... + Arduino-Webduino An extensible web server library (for use with the Arduino Ethernet Shield) + Arduino-XBee Arduino library for communicating with XBees in API mode diff --git a/docs/userguide/lib/cmd_search.rst b/docs/userguide/lib/cmd_search.rst new file mode 100644 index 00000000..2ddd31a0 --- /dev/null +++ b/docs/userguide/lib/cmd_search.rst @@ -0,0 +1,136 @@ +.. _cmd_lib_search: + +platformio lib search +===================== + +.. contents:: + +Usage +----- + +.. code-block:: bash + + platformio lib search [OPTIONS] [QUERY] + + +Description +----------- + +Search for library over ``name``, ``description`` and ``keywords`` fields from +the ``library.json`` file in the boolean mode. + +The boolean search capability supports the following operators: + +.. list-table:: + :header-rows: 1 + + * - Operator + - Description + * - ``+`` + - A leading or trailing plus sign indicates that this word must be present + in library fields (see above) that is returned. + * - ``-`` + - A leading or trailing minus sign indicates that this word must not be + present in any of the libraries that are returned. + * - ``(no operator)`` + - By default (when neither ``+`` nor ``-`` is specified), the + word is optional, but the libraries that contain it are rated higher. + * - ``> <`` + - These two operators are used to change a word's contribution to the + relevance value that is assigned to a library. The ``>`` operator + increases the contribution and the ``<`` operator decreases it. + * - ``( )`` + - Parentheses group words into subexpressions. Parenthesized groups can + be nested. + * - ``~`` + - A leading tilde acts as a negation operator, causing the word's + contribution to the library's relevance to be negative. This is useful for + marking "noise" words. A library containing such a word is rated lower than + others, but is not excluded altogether, as it would be with the ``-`` operator. + * - ``*`` + - The asterisk serves as the truncation (or wildcard) operator. Unlike the + other operators, it is appended to the word to be affected. Words match if + they begin with the word preceding the ``*`` operator. + * - ``"`` + - A phrase that is enclosed within double quote (``"``) characters matches + only libraries that contain the phrase literally, as it was typed. + +For more detail information please go to +`MySQL Boolean Full-Text Searches `_. + +Options +------- + +.. option:: + -a, --author + +Filter libraries by specified author + +.. option:: + -k, --keyword + +Filter libraries by specified keyword + +Examples +-------- + +1. Search for "1-Wire" library + +.. code-block:: bash + + $ platformio lib search 1-wire + Found N libraries: + Arduino-OneWire Control devices (from Dallas Semiconductor) that use the One Wire protocol + ... + +2. Search for Arduino-based "I2C" libraries. The ``+`` sign is here like ``AND`` + operator. + +.. code-block:: bash + + $ platformio lib search "+i2c +arduino" + Found N libraries: + i2cdevlib-Arduino-i2cdev The I2C Device Library (i2cdevlib) is a collection of uniform and well-documented classes to provide simple and intuitive interfaces to I2C devices. + i2cdevlib-Arduino-AK8975 AK8975 is 3-axis electronic compass IC with high sensitive Hall sensor technology + ... + +3. Search for libraries by "web" and "http" keywords. The ``""`` here is for + "empty" query argument. + +.. code-block:: bash + + $ platformio lib search "" --keyword web --keyword http + Found N libraries: + Arduino-Webduino An extensible web server library (for use with the Arduino Ethernet Shield) + Arduino-aJson An Arduino library to enable JSON processing with Arduino + ... + +4. Search for libraries from "Adafruit Industries" author. + +.. code-block:: bash + + $ platformio lib search "" --author "Adafruit Industries" + Found N libraries: + Adafruit-Arduino-ST7735 A library for the Adafruit 1.8" SPI display + Adafruit-Arduino-GFX A core graphics library for all our displays, providing a common set of graphics primitives (points, lines, circles, etc.) + ... + +5. Search for libraries that are compatible with Dallas temperature sensors + like DS18B20, DS18S20 and etc. + +.. code-block:: bash + + $ platformio lib search "DS*" + Found N libraries: + Arduino-OneWire Control devices (from Dallas Semiconductor) that use the One Wire protocol + ... + +6. Search for Arduino-based *X10* or *XBee* libraries. The search query that is + described below can be interpreted like ``arduino x10 OR arduino xbee``. + +.. code-block:: bash + + $ platformio lib search "+arduino +(x10 xbee)" + Found 2 libraries: + Arduino-X10 Sending X10 signals over AC power lines + Arduino-XBee Arduino library for communicating with XBees in API mode diff --git a/docs/userguide/lib/cmd_show.rst b/docs/userguide/lib/cmd_show.rst new file mode 100644 index 00000000..b7cca044 --- /dev/null +++ b/docs/userguide/lib/cmd_show.rst @@ -0,0 +1,34 @@ +.. _cmd_lib_show: + +platformio lib show +=================== + +.. contents:: + +Usage +----- + +.. code-block:: bash + + platformio lib show NAME + + +Description +----------- + +Show details about the installed library + + +Examples +-------- + +.. code-block:: bash + + $ platformio lib show Arduino-XBee + Arduino-XBee + ------------ + Author: Andrew Rapp + Keywords: xbee, protocol, radio + Version: 0.5 + + Arduino library for communicating with XBees in API mode diff --git a/docs/userguide/lib/cmd_uninstall.rst b/docs/userguide/lib/cmd_uninstall.rst new file mode 100644 index 00000000..66a26b75 --- /dev/null +++ b/docs/userguide/lib/cmd_uninstall.rst @@ -0,0 +1,31 @@ +.. _cmd_lib_uninstall: + +platformio lib uninstall +======================== + +.. contents:: + +Usage +----- + +.. code-block:: bash + + platformio lib uninstall NAME + + +Description +----------- + +Uninstall specified library + + +Examples +-------- + +.. code-block:: bash + + $ platformio lib install Arduino-IRremote + Installing Arduino-IRremote library: + Downloading [####################################] 100% + Unpacking [####################################] 100% + The library 'Arduino-IRremote' has been successfully installed! diff --git a/docs/userguide/lib/cmd_update.rst b/docs/userguide/lib/cmd_update.rst new file mode 100644 index 00000000..68d6b361 --- /dev/null +++ b/docs/userguide/lib/cmd_update.rst @@ -0,0 +1,33 @@ +.. _cmd_lib_update: + +platformio lib update +===================== + +.. contents:: + +Usage +----- + +.. code-block:: bash + + platformio lib update + + +Description +----------- + +Check or update installed libraries + + +Examples +-------- + +.. code-block:: bash + + $ platformio lib update + Updating Arduino-IRremote library: + Versions: Current=24ba950f5c, Latest=24ba950f5c [Up-to-date] + Updating Arduino-Webduino library: + Versions: Current=3631af8e02, Latest=3631af8e02 [Up-to-date] + Updating Arduino-XBee library: + Versions: Current=0.5, Latest=0.5 [Up-to-date] diff --git a/docs/userguide/lib/index.rst b/docs/userguide/lib/index.rst new file mode 100644 index 00000000..d1d5802a --- /dev/null +++ b/docs/userguide/lib/index.rst @@ -0,0 +1,22 @@ +.. _userguide_lib: + +Library Manager +=============== + +To print all available commands and options use: + +.. code-block:: bash + + $ platformio lib --help + $ platformio lib COMMAND --help + + +.. toctree:: + :maxdepth: 2 + + cmd_install + cmd_list + cmd_search + cmd_show + cmd_uninstall + cmd_update