In case you experience issues or bugs using this package, please feel free to submit an issue on our issue page.
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]
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.
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
Forkbutton 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 firstname.lastname@example.org:YourAccount/chemtools.git
Create a branch to hold your changes:
$ git checkout -b your_feature_branch_name
Include your name and email in the
AUTHORSfile 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 requestto 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.
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
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
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
# 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.