diff --git a/docs/librarymanager/config.rst b/docs/librarymanager/config.rst index b0baf3bf..ff048e32 100644 --- a/docs/librarymanager/config.rst +++ b/docs/librarymanager/config.rst @@ -3,15 +3,15 @@ library.json ============ -Libraries are defined by a manifest file ``library.json``. This is a -`JSON-style `_ file. Any data in -``library.json`` should be represented via +*PlatformIO*-suitable library should be defined by a manifest file +``library.json`` in a `JSON-style `_. +A data in ``library.json`` should be represented via `associative array `_ (name/value pairs). An order doesn't make a sense. The allowable fields (names from pairs) are described below. The fields (:ref:`libjson_name`, :ref:`libjson_description` and :ref:`libjson_keywords`) -will be displayed in search/lookup results on the :ref:`cmd_lib_search` +will be displayed in search results on the :ref:`cmd_lib_search` (*CLI*) and the *WebSite* that can be used to search for libraries. .. contents:: @@ -23,12 +23,12 @@ will be displayed in search/lookup results on the :ref:`cmd_lib_search` **Required** | Type: ``String`` | Max. Length: 50 -The name of the library. +A name of the library. * Must be unique. * Should be slug style for simplicity, consistency and compatibility. - Example: Arduino-SPI -* Title Case, Aa-z, can contain digits, can contain dash (but not start/end + Example: *Arduino-SPI* +* Title Case, Aa-z, can contain digits and dashes (but not start/end with them). * Consecutive dashes are not allowed. @@ -52,13 +52,13 @@ with it. **Required** | Type: ``String`` | Max. Length: 255 -The keyword should be lowercased, can contain a-z, digits and dash (but not -start/end with them). A list from keywords can be specified with -separator ``,``. - Used for search by keyword. Helps make your library easier to discover without people needing to know its name. +The keyword should be lowercased, can contain a-z, digits and dash (but not +start/end with them). A list from the keywords can be specified with +separator ``,``. + .. _libjson_version: @@ -68,9 +68,9 @@ people needing to know its name. *Required* if :ref:`libjson_repository` field is not defined | Type: ``String`` | Max. Length: 20 -The version of the current library source code. +A version of the current library source code. -* Can contain a-z, digits, dots and dash. +* Can contain a-z, digits, dots or dash. * `Semantic Versioning `_ is recommended. * A `CVS `_ revision from the latest commit. Example: ``13`` (*SVN*) or first 10 @@ -78,8 +78,8 @@ The version of the current library source code. .. note:: You can omit :ref:`libjson_version` field and define - :ref:`libjson_repository` field. In this situation - *PlatformIO-API Crawler* will use the CVS-revision from the latest commit. + :ref:`libjson_repository` field. In this case + *PlatformIO-API Crawler* will use the *CVS*-revision from the latest commit. .. _libjson_author: @@ -89,7 +89,7 @@ The version of the current library source code. *Required* if :ref:`libjson_repository` field is not defined | Type: ``Object`` -An author's contact information +An author contact information * ``name`` Full name (**Required**) * ``email`` @@ -108,8 +108,8 @@ Example: .. note:: You can omit :ref:`libjson_author` field and define - :ref:`libjson_repository` field. Only *GitHub-based* repository is - supported now. In this situation + :ref:`libjson_repository` field. The only *GitHub-based* repository is + supported now. In this case *PlatformIO-API Crawler* will use information from `GitHub API Users `_. @@ -155,7 +155,7 @@ of archive (``.zip`` or ``.tar.gz``). If :ref:`libjson_include` field is a type of ``String``, then *PlatformIO-API Crawler* will recognize it like a "relative path inside -repository/archive to library source code". See example below where only +repository/archive to library source code". See example below where the only source code from the relative directory ``LibrarySourceCodeHere`` will be included. @@ -204,7 +204,7 @@ Pattern Meaning *Optional* | Type: ``String`` or ``Array`` | `Glob Pattern `_ -Exclude the directories and files which will match with :ref:`libjson_exclude` +Exclude the directories and files which match with :ref:`libjson_exclude` patterns. @@ -215,7 +215,7 @@ patterns. *Optional* | Type: ``Array`` -The list of dependent libraries. They will be installed automatically with +A list of dependent libraries. They will be installed automatically with :ref:`cmd_lib_install` command. Example: diff --git a/docs/librarymanager/create.rst b/docs/librarymanager/create.rst index 88f88c13..5e2351eb 100644 --- a/docs/librarymanager/create.rst +++ b/docs/librarymanager/create.rst @@ -4,7 +4,7 @@ Creating Library ================ -*PlatformIO* :ref:`librarymanager` doesn't has any requirements to a library +*PlatformIO* :ref:`librarymanager` doesn't have any requirements to a library source code structure. The only one requirement is library's manifest file - :ref:`library_config`. It can be located inside your library or in the another location where |PIOAPICR| will have *HTTP* access. @@ -17,9 +17,9 @@ Source Code Location There are a several ways how to share your library with the whole world (see `examples `_). -Also, you can hold a lot of libraries inside the one repository/archive in the -different folders. In this case please use :ref:`libjson_include` field to -specify the relative path to your library's source code. +You can hold a lot of libraries (split into separated folders) inside the one +repository/archive. In this case please use :ref:`libjson_include` +field to specify the relative path to your library's source code. At GitHub @@ -27,8 +27,8 @@ At GitHub **Recommended** -If the library source code is located at `GitHub `_, then -you **need to specify** only these fields in :ref:`library_config`: +If a library source code is located at `GitHub `_, then +you **need to specify** only these fields in the :ref:`library_config`: * :ref:`libjson_name` * :ref:`libjson_keywords` @@ -36,7 +36,7 @@ you **need to specify** only these fields in :ref:`library_config`: * :ref:`libjson_repository` |PIOAPICR| will populate the rest fields, like :ref:`libjson_version` or -:ref:`libjson_author` with actual information from *GitHub*. +:ref:`libjson_author` with an actual information from *GitHub*. Example: @@ -56,8 +56,8 @@ Example: Under CVS (SVN/GIT) ^^^^^^^^^^^^^^^^^^^ -|PIOAPICR| can operate with the library source code that is under *CVS* control. -The list of **required** fields in :ref:`library_config` will look like: +|PIOAPICR| can operate with a library source code that is under *CVS* control. +The list of **required** fields in the :ref:`library_config` will look like: * :ref:`libjson_name` * :ref:`libjson_keywords` @@ -86,13 +86,13 @@ Example: } } -Packed in achive (Zip, Tar.Gz) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Packed into Archive +^^^^^^^^^^^^^^^^^^^ -You can manually archive your library source code and host it in the *Internet*. -Then you should specify additional fields, like :ref:`libjson_version` and -:ref:`libjson_downloadurl`. The final list of **required** fields in -:ref:`library_config` will look like: +You can manually archive (*Zip, Tar.Gz*) your library source code and host it +in the *Internet*. Then you should specify the additional fields, +like :ref:`libjson_version` and :ref:`libjson_downloadurl`. The final list +of **required** fields in the :ref:`library_config` will look like: * :ref:`libjson_name` * :ref:`libjson_keywords` @@ -121,9 +121,10 @@ Then you should specify additional fields, like :ref:`libjson_version` and Register -------- -* The library must adhere to the :ref:`library_config` specification. -* There must be public *HTTP* access to library :ref:`library_config` file. +The registration requirements: + +* A library must adhere to the :ref:`library_config` specification. +* There must be public *HTTP* access to the library :ref:`library_config` file. Now, you can :ref:`register ` your library and allow others to :ref:`install ` it. - diff --git a/docs/librarymanager/index.rst b/docs/librarymanager/index.rst index 8f7a857f..bef1759e 100644 --- a/docs/librarymanager/index.rst +++ b/docs/librarymanager/index.rst @@ -3,7 +3,7 @@ Library Manager =============== -*"The missing libraries manager for embedded platforms"*, - inspired by +*"The missing library manager for embedded platforms"*, - inspired by `npm `_ and `bower `_ package managers for web.