cookiecutter based template
added some low-level TravisCI with pytest
Here we provide some details about the project setup. Most of the choices are explained in the guide <https://guide.esciencecenter.nl>_. Links to the relevant sections are included below.
Feel free to remove this text when the development of the software package takes off.
For a quick reference on software development, we refer to the software guide checklist <https://guide.esciencecenter.nl/best_practices/checklist.html>_.
Once your Python package is created, put it under
version control <https://guide.esciencecenter.nl/best_practices/version_control.html>!
We recommend using git <http://git-scm.com/> and github <https://github.com/>_.
.. code-block:: console
cd g git init git add -A git commit
To put your code on github, follow this tutorial <https://help.github.com/articles/adding-an-existing-project-to-github-using-the-command-line/>_.
This repository is set up with Python versions:
- 2.7
Add or remove Python versions based on project requirements. The guide <https://guide.esciencecenter.nl/best_practices/language_guides/python.html>_ contains more information about Python versions and writing Python 2 and 3 compatible code.
You can use either pip or conda for installing dependencies and package management. This repository does not force you to use one or the other, as project requirements differ. For advice on what to use, please check the relevant section of the guide <https://guide.esciencecenter.nl/best_practices/language_guides/python.html#dependencies-and-package-management>_.
- Dependencies should be added to
setup.pyin theinstall_requireslist.
You can distribute your code using pipy or conda. Again, the project template does not enforce the use of either one. The guide <https://guide.esciencecenter.nl/best_practices/language_guides/python.html#building-and-packaging-code>_ can help you decide which tool to use for packaging.
-
Tests should be put in the
testsfolder. -
The testing framework used is
PyTest <https://pytest.org>_PyTest introduction <http://pythontesting.net/framework/pytest/pytest-introduction/>_
-
Tests can be run with
python setup.py test- This is configured in
setup.pyandsetup.cfg
- This is configured in
-
Use
Travis CI <https://travis-ci.com/>_ to automatically run tests and to test using multiple Python versions- Configuration can be found in
.travis.yml Getting started with Travis CI <https://docs.travis-ci.com/user/getting-started/>_
- Configuration can be found in
-
TODO: add something about code quality/coverage tool?
-
Relevant section in the guide <https://guide.esciencecenter.nl/best_practices/language_guides/python.html#testing>_
-
Documentation should be put in the
docsfolder. The contents have been generated usingsphinx-quickstart(Sphinx version 1.6.5). -
We recommend writing the documentation using Restructured Text (reST) and Google style docstrings.
Restructured Text (reST) and Sphinx CheatSheet <http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html>_Google style docstring examples <http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>_.
-
To generate html documentation run
python setup.py build_sphinx- This is configured in
setup.cfg - Alternatively, run
make htmlin thedocsfolder.
- This is configured in
-
The
docs/_staticanddocs/_templatescontain an (empty).gitignorefile, to be able to add them to the repository. These two files can be safely removed (or you can just leave them there). -
To put the documentation on
Read the Docs <https://readthedocs.org>_, log in to your Read the Docs account, and import the repository (under 'My Projects').- Include the link to the documentation in this README_.
-
Relevant section in the guide <https://guide.esciencecenter.nl/best_practices/language_guides/python.html#writingdocumentation>_
- Check your code style with
prospector - You may need run
pip install .[dev]first, to install the required dependencies - You can use
yapfto fix the readability of your code style andisortto format and group your imports Relevant section in the guide <https://guide.esciencecenter.nl/best_practices/language_guides/python.html#coding-style-conventions>_
- Document changes to your software package
Relevant section in the guide <https://guide.esciencecenter.nl/software/releases.html#changelogmd>_
- To allow others to cite your software, add a
CITATION.cfffile - It only makes sense to do this once there is something to cite (e.g., a software release with a DOI).
- To generate a CITATION.cff file given a DOI, use
doi2cff <https://github.com/citation-file-format/doi2cff>_. Relevant section in the guide <https://guide.esciencecenter.nl/software/documentation.html#citation-file>_
- Information about how to behave professionally
Relevant section in the guide <https://guide.esciencecenter.nl/software/documentation.html#code-of-conduct>_
- Information about how to contribute to this software package
Relevant section in the guide <https://guide.esciencecenter.nl/software/documentation.html#contribution-guidelines>_
- List non-Python files that should be included in a source distribution
Relevant section in the guide <https://guide.esciencecenter.nl/best_practices/language_guides/python.html#building-and-packaging-code>_
- List of licenses of the project and dependencies
Relevant section in the guide <https://guide.esciencecenter.nl/best_practices/licensing.html#notice>_
To install g, do:
.. code-block:: console
git clone https://github.com/Utrecht University/g.git cd g pip install .
Run tests (including coverage) with:
.. code-block:: console
python setup.py test
Documentation
.. _README:
Include a link to your project's full documentation here.
Contributing
If you want to contribute to the development of GLOFRIM X,
have a look at the contribution guidelines <CONTRIBUTING.rst>_.
License
Copyright (c) 2018, Jannis Hoch
GNU General Public License v3
Credits
This package was created with Cookiecutter <https://github.com/audreyr/cookiecutter>_ and the NLeSC/python-template <https://github.com/NLeSC/python-template>_.