.. include:: ../README.rst

Upgrade Package Structure
=========================

Packages generated with pkglts contains three different types of files:

 - Configuration files for pkglts, which are all located inside a '.pkglts'
   directory at the root of your package. This directory especially contains a
   'pkg_cfg.json' resource file that contains all the information necessary to
   regenerate your package in order to take into account new developments in the
   way of packaging or new options you added to your package.
 - Files that contain at least one 'pkglts' tag that have been automatically
   generated by pkglts. Everything inside a pkglts section is regenerated every
   time the user call 'regenerate' on his package and are not meant to be
   modified. Between pkglts sections the user is free to add his own code that
   won't be touched in the regenerate process.
 - developer data and modules edited by hand which contains the actual python
   code of the package independently of the structure of the package. pkglts
   will never touch them. If they conflict with some files used by a newly
   added option, the user will be prompted and will have to solve the conflict
   in order to install the option.

Every time you make changes to the structure of your package by adding a new
option for example, a call to 'pmg regenerate' is mandatory to rebuilt the
package structural files::

    (dvlpt)toto$ pmg rg

This phase will never overwrite any files you modified or created. You'll be prompted
in case of conflicts but it is your responsibility to solve them and relaunch the
command.

It is also good practice to regenerate your package from time to time to take
into account the latest version of pkglts which will reflect the latest
development in the way to package things.

.. _pkglts_git: https://github.com/revesansparole/pkglts

.. _pkg_struct_func:

Add Package Structure Functionality
===================================

Pkglts provides a set of options to introduce new functionality to an
already existing package:

 - :doc:`option/base/main`: base option, basic package management
 - :doc:`option/license/main`: will help the developer to choose a license and add the relevant
   files
 - :doc:`option/doc/main`: Add some documentation to your package
 - :doc:`option/test/main`: basic unitests using Nose_
 - :doc:`option/coverage/main`: add code coverage_ to the basic test configuration
 - :doc:`option/pysetup/main`: make your package distributable with setuptools (i.e. setup.py)
 - :doc:`option/data/main`: will guide through all the steps to add non python files to a package
 - :doc:`option/github/main`: will guide through all the step to safely store the package on Github_
 - :doc:`option/gitlab/main`: will guide through all the step to safely store the package on a Gitlab_ repo
 - :doc:`option/readthedocs/main`: step by step guide to have your documentation on ReadTheDocs_
 - :doc:`option/travis/main`: will guide through all the steps to use Travis-CI_ for continuous integration of your package
 - :doc:`option/tox/main`: defines config files to use multi environment testing, Tox_
 - :doc:`option/flake8/main`: install and config Flake8_ tools to check for code compliance to PEP8_
   guidelines.
 - :doc:`option/pypi/main`: step by step guide and configuration to upload package on PyPi_.

.. _Travis-CI: http://travis-ci.org/
.. _Tox: http://testrun.org/tox/
.. _Sphinx: http://sphinx-doc.org/
.. _ReadTheDocs: https://readthedocs.org/
.. _Github: https://github.com/
.. _Gitlab: https://framagit.org/
.. _Nose: http://nose.readthedocs.io/en/latest/index.html
.. _coverage: https://pypi.python.org/pypi/coverage
.. _Flake8: https://pypi.python.org/pypi/flake8
.. _PyPi: https://pypi.python.org/pypi
.. _PEP8: https://www.python.org/dev/peps/pep-0008/

Install a new option
--------------------

To install a new option call the 'add' action::

    (dvlpt)toto$ pmg add license

The script will perform different tasks sequentially:

 - Check if this option requires other options in order to be installed:
   e.g. the 'pysetup' option requires all 'base, 'doc', 'test', 'license' and 'version'
   in order to run properly.
 - Check if this option requires some extra packages in order to setup:
   e.g. the 'test' option depends on the Nose_ package to function properly.


.. note:: Nothing will be installed without your consent

Multiple call to add options can be serialized but you explicitly needs to call
regenerate to see the action of the new options on your package::

    (dvlpt)toto$ pmg rg


Before calling 'regenerate' however, take the time to browse through 'pkg_cfg.json'
in the '.pkglts' directory to edit the parameters relevant for your option.

Install example files
---------------------

Some options come with example files that can be installed with the special
directive::

    (dvlpt)toto$ pmg example test


The files will be directly installed without the need to a regenerate call. You
can reinstall them at any time (you'll be prompted for action if conflicts occur).

Extra tools
===========

Some options of pkglts provide tools to make the life of package manager easier.

- :doc:`option/doc/history`: Regenerate the history of your package from associated tags
- :doc:`option/pysetup/reqs`: Find all your dependencies
- :doc:`option/version/bump`: Increase your package version number

.. warning:: Work In Progress

Contributing
============

You can contribute to this package by:

 - improving the documentation
 - correcting some bugs
 - closing a few issues
 - implementing a new option to add a new functionality to package structures


.. :begin_links_section:
.. _base: http://pkglts.readthedocs.org/en/latest/option/base/main.html
