Merge pull request #4289 from authmillenon/doc/enh/pkg

doc: move pkg/PORTING.md and pkg/USING.md to doxygen

doc/doxygen/riot.doxyfile

@@ -758,8 +758,8 @@ INPUT                  = ../../doc.txt \
                          ../../cpu \
                          ../../boards \
                          ../../drivers \
-                         ../../sys \
                          ../../pkg \
+                         ../../sys \
                          src/ \
                          src/mainpage.md \
                          src/creating-an-application.md \

pkg/PORTING.md

@@ -1,22 +0,0 @@
-This directory provides some porting information for libraries and programs to
-use with RIOT (to build an external module). If you'd like to add a package to
-RIOT you need to add a directory with the name of your package to this directory.
-Your directory should contain at least two files:
-
- * **One or more patch files** - Your patches of the upstream application of
-   the package to make it build with RIOT.
- * **Makefile**- A Makefile describing how to get the upstream application,
-   apply the patch and how to build the package as a RIOT module.
-   A rough template for several methods of acquiring a package is provided in
-   Makefile.git, Makefile.http, and Makefile.svn
-
-### Creating a patch with git
-
-Assuming your upstream application resides in a git repository, you can create
-the patch files as follows:
- * checkout the targeted version of the upstream application
- * conduct necessary changes (e.g. edit, add, or remove some files)
- * commit your changes using `git commit`
- * create the patch files using `git format-patch -n HEAD~N` where `N` is the
-   number of commits you did
- * move the resulting patch files to the corresponding subfolder of pkg

pkg/USING.md

@@ -1,5 +0,0 @@
-Packages are included to your application as external modules. Thus you only
-have to add the following line to your application (and update your INCLUDE path
-accordingly):
-
-    USEPKG += <pkg_name>

pkg/doc.txt

@@ -1,15 +1,44 @@
-/*
- * Copyright (C) 2015 INRIA
- *
- * This file is subject to the terms and conditions of the GNU Lesser
- * General Public License v2.1. See the file LICENSE in the top level
- * directory for more details.
- */
-
 /**
- * @defgroup    pkg Packages
- * @brief       RIOT supports the integration of external libraries. These
- *              libraries can be used as BSD-like packages, i.e. they are
- *              downloaded automatically at compile-time (if needed) and linked
- *              against RIOT.
+ * @defgroup pkg   Packages
+ * @{
+ * @brief          External libraries and applications
+ *
+ * Using packages
+ * ==============
+ * To add a package to the list of compiled modules you have to add it to the
+ * `USEPKG` macro in your application's Makefile. If the package provides
+ * header files you might need to update the `INCLUDE` macro, too:
+ *
+ * ~~~~~~~~ {.mk}
+ * USEPKG += <pkg_name>
+ * INCLUDE += $(RIOTBASE)/pkg/<pkg_name>/...
+ * ~~~~~~~~
+ *
+ * Porting an external library
+ * ===========================
+ * Structure of a package
+ * ----------------------
+ * This module provides porting information for libraries and applications to use
+ * with RIOT (to build an external module). If you'd like to add a package to RIOT
+ * you need to add a directory with the name of your package to this directory.
+ * This directory should contain at least two files:
+ *
+ *  * **Zero or more patch files**: Your patches of the upstream application of
+ *    the package to make it build with RIOT.
+ *  * **Makefile**: A Makefile describing how to get the upstream application,
+ *    apply the patch and how to build the package as a RIOT module.
+ *    A rough template for several methods of acquiring a package is provided in
+ *    `pkg/Makefile.git`, `pkg/Makefile.http`, and `pkg/Makefile.svn`
+ *
+ * Creating a patch with git
+ * -------------------------
+ * Assuming your upstream library resides in a git repository, you can create the
+ * patch files as follows:
+ *  * checkout the targeted version of the upstream application
+ *  * create a new branch (e.g. `riot-port`)
+ *  * conduct necessary changes (e.g. edit, add, or remove some files)
+ *  * commit your changes using `git commit`
+ *  * create the patch files using `git format-patch -n riot-port`
+ *  * move the resulting patch files to the corresponding subfolder of pkg
+ * @}
  */