Developer Guidelines

Submitting Issues

In case you experience issues or bugs using this package, please feel free to submit an issue on our issue page.

Building ChemTools

We use github to host our repository. You can download our latest sources with command:

$ git clone https://github.com/QuantumElephant/chemtools.git chemtools

For developer, it is more convenient to build ChemTools in place. Before you build ChemTools, ensure you have all the required dependencies installed. You can build ChemTools with the commands:

$ pip install -e .[dev]

Running Tests

Nosetests are recommended after built to ensure all the parts of ChemTools working properly:

$ nosetests -v chemtools

At this stage, some UserWarning messages are printed in between tests which is expected. However, no test should fail.

Contributing Code

The preferred way to contribute to ChemTools is fork from our main repo on github, make some changes, and then make a Pull request:

• Fork the main repo from ChemTools github page: Clicking on the Fork button near the top right of the page. This will create a copy of the latest code under your own account.

• Add your forked repo to the remote list of your local repo:

  $ git remote add your_remote_name git@github.com:YourAccount/chemtools.git
  

• Create a branch to hold your changes:

  $ git checkout -b your_feature_branch_name
  

• Include your name and email in the AUTHORS file at the root directory of ChemTools. Ensure the name and email are the same as your git config. You can check your name and email with the commands:

  $ git config user.name
  $ git config user.email
  

• Work on this branch locally and make some changes. When you’ve done editing, use the command:

  $ git add files_you_modified
  $ git commit
  

  to write down the changes your made and save it.

• Push your changes to your own remote repo:

  $ git push your_remote_name your_feature_branch_name
  

• Finally, go to your forked github repo page, click Pull request to send your changes. All the changes need to pass the automatic quality test before your pull request gets reviewed. You can go to the “Pull request” page of the main repo to check the status of the test and fix the errors if any of them fail.

Building Documentation

If you are interested in generating the documentation from source, the following packages are also needed:

• Sphinx >=1.3.1: http://sphinx.pocoo.org/
• sphinxcontrib-bibtex >= 0.3.5: https://pypi.python.org/pypi/sphinxcontrib-bibtex
• IPython >= 3.2.1: https://ipython.org/install.html

To install these dependencies,

$ pip install -e .[doc]

The Sphinx Read-The-Docs theme as well as Sphinx Gallery customized for ChemTools can be obtained by cloning the repository as a submodule from ChemTools parent directory:

$ git submodule update --init --recursive

To automatically generate API documentation and generate HTML:

$ cd doc
$ make clean
$ make html

To open the documentation in your default browser, either click on _build/html/index.html file directly, or run the command below from terminal:

$ open _build/html/index.html

In case this command did not work, for example on Ubuntu 16.04 you may get a message like “Couldn’t get a file descriptor referring to the console”, try:

$ see _build/html/index.html

Quality Assurance

When making a pull request to contribute to the ChemTools repository, the code is remotely tested to see if it passes all the tests and meets ChemTools’ quality standards. To run the tests locally, please refer to Testing. If you are interested to run the quality assurance scripts locally, first install the dependencies below:

• PyLint >= 1.5.0: https://www.pylint.org/
• pycodestyle >= 2.0.0: http://pycodestyle.readthedocs.io/
• pydocstyle >= 1.0.0: http://pydocstyle.readthedocs.io/
• coverage >= 4.1: https://coverage.readthedocs.io/
• Git >= 1.8: https://git-scm.com/
• GitPython >= 2.0.5: http://gitpython.readthedocs.io/

Then, download the quality assurance code by cloning the corresponding submodule:

$ git submodule update --init tools/inspector

And, run the module’s bash script to setup some pre-commit hooks and copy files to run the quality assurance scripts individually:

# it is installed in the relative path
$ cd tools/inspector
$ ./install.sh
$ cd ../..

At this stage, the quality assurance tests can be simulated from the ChemTools parent directory. For example to run pylint check,

# from ChemTools parent directory
$ ./tools/inspector/qa/simulate_trapdoor_pr.py tools/inspector/qa/trapdoor_pylint.py

To run all of the quality assurance scripts,

# from ChemTools parent directory
$ for i in tools/inspector/qa/trapdoor_*; do tools/inspector/qa/simulate_trapdoor_pr.py $i; done

Note that you should be developing on a feature (not master) branch and merging/rebasing to the updated master when complete. There should be also no uncommitted changes when running these scripts.