Developer Guide¶
Topics¶
Installing an editable copy of PyARPES¶
Make an Anaconda environment or
virtualenv
for your installation of PyARPESClone the respository
git clone https://gitlab.com/lanzara-group/python-arpes
or
git clone https://github.com/chstan/arpes
Install PyARPES into your conda environment/virtualenv with
pip install -e .
Tests¶
Prerequisites¶
You need some additional Python packages as well as Yarn.
Installing Test Requirements¶
Install additional test requirements by running
$> conda env update --file environment-update-test.yml
or by manually installing the requirements.
Installing Yarn¶
Follow instructions for your platform at yarnpkg.com.
Running Tests¶
yarn test
Getting test coverage information¶
If you want to generate coverage information, you can run the coverage command and serve results as HTML locally.
In one terminal start the Python HTTP server with:
$> python -m http.server --directory htmlcov
Now, refresh coverage information with
yarn coverage
finally, you can view results at localhost:8000.
When to write tests¶
If you are adding a new feature, please consider adding a few unit tests. Additionally, all bug fixes should come with a regression test if they do not require a very heavy piece of fixture data to support them.
To write a test that consumes data from disk using the standard PyARPES
loading conventions, fixtures are available in tests/conftest.py
.
The tests extent in test_basic_data_loading.py
illustrate using
these fixtures.
Contributing Documentation¶
Adding a new section¶
To add a new section to the documentation, modify
_sidebar_partial.md
and add any other associated files. Then follow
the instructions below for rebuilding the documentation.
Updating existing documentation¶
To update existing documentation you can simply modify the appropriate files. You should not need to rebuild the documentation for your changes to take effect, but there is no harm is doing so.
Rebuilding the documentation¶
To rebuild the documentation you will need to have both
sphinx and
pandoc installed. Then from the directory that
contains the setup.py
file
Refresh Sphinx sources with
sphinx-apidoc
:python -m sphinx.apidoc --separate -d 3 --tocfile toc -o source arpes --force
Build Sphinx documentation to ReStructuredText:
make clean && make rst
Convert ReStructuredText to Markdown:
./source/pandoc_convert.py
Run
docsify
to verify changes:docsify serve ./docs
As desired publish to docs site by pushing updated documentation
Note Sometimes sphinx-doc
has trouble converting modules to
ReStructured Text.versioning This typically manifests with a
KeyError
in docutils
. This occurs when the docstrings do not
conform to the standard for ReStructuredText. The most common problem
encountered is due to bare hyperlinks, which are incompatible with the
unique hyperlink format in RST.
Style¶
We don’t have any hard and fast style rules. As a coarse rule of thumb, if your code scans well and doesn’t use too many short variable names there’s no issue.