Welcome to addme’s documentation!¶
A template Python package¶
This repo contains a tiny Python package with a number of features:
- The API is autodocumented using Sphinx, and can be viewed on ReadTheDocs.
- Demonstrates how to properly use logging.
- Demonstrates how to generate code coverage report
- Demonstrates how to set up CI with Travis, which runs unit tests and a linter
- Demonstrates how to use
`setup.py`to enable the package to be installed using`pip`.
References¶
Autodocumented API¶
This relies on the use of Python docstrings combined with Sphinx.
Google docstring style can be found here: http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
More information on setting up Sphinx can be found here: https://samnicholls.net/2016/06/15/how-to-sphinx-readthedocs/
Note that you need to rerun
sphinx-apidoc -o source/ ../addme/
Whenever you change the structure of your modules. See here: https://stackoverflow.com/questions/28481471/sphinx-keeping-the-api-updated/28481785#28481785
Pip install¶
To pip install, we need a valid `setup.py` file, and then the package can be installed from Github using:
pip install git+https://github.com/RobinL/python_package_template.git
Unit testing¶
Having reviewed the options, I chose to use the standard unittest library for unit testing
It seems simplest to use the default Python module. The main advantage of `pytest` in a simple project seems to be less boilerplate, but the differences are not enormous.
To run the tests locally, we can just run:
python -m unittest discover
In the travis file we run them, whilst also producing a coverage report and syncing with codecov.io
Things to remember:¶
ReadTheDocs will fail by default if your project has dependencies (e.g. pandas) To correct, go to Advanced Settings in the ReadTheDocs web interface, and point it at your requirements.txt file.