Publishing Contributions

GBasis, like all HORTON 3 modules, has a robust build system included which builds off the Conda architecture and Travis-CI. This ensures our codebase meets certain quality standards.

When making a new feature for Gbasis, you should fork the main repository and then make a pull request from your fork to the master branch. The pull request will then be verified by Travis-CI. Travis checks for several things:

  • PEP-8 (code style) compliance
  • PEP-257 (docstring) compliance
  • Unit tests pass
  • Unit testing coverage
  • Linux/OSX compatibility

You can examine the Travis-CI error log if your code fails and make the appropriate changes. Every commit to your pull request will be tested automatically.

Tips

You should check your code before making a pull request to save yourself some trouble. Using a modern IDE like Pycharm will go a long way to making sure your code complies with PEP-8, PEP-257, and so forth. Use the code refactoring features.

You will also find that testing locally can save you some time. Run nosetests on your own machine before submitting your PR.

Building with Conda on your own machine will emulate lots of the build tests and give you a virtualenv that will be more reliable.

The instructions for compiling with Conda are listed in Installation (from source). This is the build which will be executed by Travis-CI when making a pull request.

Documentation changes

Most of the documentation builds happen automatically. The .rst files within doc/ are processed by Sphinx and associated scripts. Docstring changes in the code are automatically included in the new docs. If write user documentation for your feature (which would be greatly appreciated), you can add a new .rst or modify an existing one. The docs will then be built by ReadTheDocs upon merging to master.

You can test your docs beforehand by running this command in the docs directory. Note that this will not work unless you have all the doc building dependencies installed.

./gen_docs.sh
make html

Since Sphinx cannot parse docstring unless it imports the module, this means:

  1. Your code must be syntactically correct and importable
  2. If your code contains Cython modules, they must be built before building the docs.

More concretely, if you ran cleanfiles.sh and gen_docs.sh immediately afterwards, you will get errors. Also, if you build using Conda-build, your docs will not build unless you install the package into your environment first.

Introducing new dependencies

Sometimes a contribution will introduce a dependency on another library. This will need to be added to the conda virtualenv when building the package for testing. This can be done in tools/conda.recipe/meta.yaml. Depending on whether your dependency is a Python library, or a compiled C/C++ library, it needs to go in different sections.

The host section is for packages which will be installed into the build environment. This is for C/C++ dependencies.

host:
- python ={{ MYCONDAPY }}
- libint
- cython >=0.24.1
- numpy
- setuptools
- nose

The run section is for installing dependencies on the user’s machine. This is for Python dependencies. This is also for libraries which need to be dynamically linked. In theory the Conda build tools will automatically add the linked libraries from host here as well, but in practice the process is not reliable. You are advised to add them in as well.

run:
- python >=3
- numpy
- scipy
- nose
- libint

For details on the meta.yaml file, read the conda-build documentation. Some commands within the documentation are incorrect/out-of-date. You have been forewarned…