This is place for developer information that does not belong in the user guides or the API reference, but is useful for people developing or contributing to AnyPyTools.
All code changes must go through the pull request review procedure.
AnyPyTools use PEP8 (with some relaxations to the line length) to ensure consistency throughout the code base.
How to Test¶
Prep your environment for running the tests:
$ pip install -r requirements-tests.txt
Running the Tests¶
Run all the tests using pytest:
$ pytest --flake8
If you want to run specific tests you can specify the test names to execute. For example to run test_aliases:
$ pytest abcutils.py
Note that you can pass multiple test names in the above examples:
$ pytest abcutils.py datautils.py
How to Document¶
Documentation takes many forms. This will guide you through the steps of successful documentation.
No matter what language you are writing in, you should always have documentation strings along with you code. This is so important that it is part of the style guide. When writing in Python, your docstrings should be in reStructured Text using the numpydoc format.
The docstrings that you have written will automatically be connected to the
website, once the appropriate hooks have been setup. At this stage, all
documentation lives within AnyPyTools’s top-level
We uses the sphinx tool to manage and generate the documentation, which
you can learn about from the sphinx website.
If you want to generate the documentation, first AnyPyTools itself must be installed
and then you may run the following command from the
~/AnyPyTools/docs $ make html
All user-facing API should be added to the sphinx documentation. This should be done the
first time that the module, class or function appears in a pull request. From here, call the
mymod. The following explains how to add hooks.
Python documentation lives in the
First, create a file in this directory that represents the new module called
docs/api directory matches the structure of the
So if your module is in a sub-package, you’ll need to go into the sub-package’s
directory before creating
The contents of this file should be as follows:
.. _AnyPyTools_mymod: ======================================= My Awesome Module -- :mod:`AnyPyTools.mymod` ======================================= .. currentmodule:: AnyPyTools.mymod .. automodule:: AnyPyTools.mymod :members:
This will discover all of the docstrings in
mymod and create the
appropriate webpage. Now, you need to hook this page up to the rest of the
Go into the
index.rst file in
AnyPyTools/docs/api and add
mymod to the appropriate
toctree (which stands for table-of-contents
Building the Website¶
Building the website/documentation requires the following dependencies:
Procedure for modifying the website¶
The AnyPyTools website source files are located in the
A developer first makes necessary changes, then rebuilds the website locally
by executing the command:
$ make html
This will generate html files for the website in the
The developer may view the local changes by opening these files with their
favorite browser, e.g.:
$ google-chrome _build/html/index.html
Once the developer is satisfied with the changes, the changes should be committed and pull-requested per usual. Once the pull request is accepted, the documentation is build automatically by travis CI and pushed to the anybody-research-group/anypytools-docs repository from where it is published with github pages.
Branches and Releases¶
Mainline AnyPyTools development occurs on the
master branch. Other branches
may be used for feature development (topical branches) or to represent
past and upcoming releases.
If you have a new fix that needs to be in the next release, you should make a topical branch and then pull request it into the release branch. After this has been accepted, the topical branch should be merged with master as well.
You can cleanup your local repository of transient files such as *.pyc files created by unit testing by running:
$ rm -f AnyPyTools/*.pyc tests/*.pyc $ rm -fr build
Performing the Release¶
Update and push the release log
Update version number in
Ensure test pass
Make PR on GitHub, and check docs compile correctly on travis
Create a tag with the version number and push it.
- Crate PYPI pckage
python setup.py sdist
twine upload dist/*
Update the conda forge package on https://github.com/conda-forge/anypytools-feedstock
Portions of this page have been forked from
Xonsh documentation, Copyright 2014-2017, the Xonsh Development Team. All rights reserved.
PyNE documentation,Copyright 2011-2015, the PyNE Development Team. All rights reserved.