Contributing¶
The code is maintained in a git repository, the official repository is on github. You’re welcome to contribute and submit pull requests on github. If you’re unsure how or what to do, you can ask for help in the community forum. If you want to become a member of the developer team, just ask ;-)
To keep consistency, we ask you to comply with the following guidelines for contributions:
Use a code style based on PEP 8. The git repo includes a config file
.style.yapf
for the python package yapf. yapf is a tool to auto-format code, e.g., by the commandyapf -i some/file
(-i for “in place”). We run yapf on a regular basis on the github master branch. If your branch diverged, it might help to run yapf before merging.
Note
Since no tool is perfect, you can format some regions of code manually and enclose them
with the special comments # yapf: disable
and # yapf: enable
.
Every function/class/module should be documented by its doc-string (c.f. PEP 257), additional documentation is in
doc/
. The documentation uses reStructuredText. If you’re new to reStructuredText, read this introduction. We use the numpydoc extension to sphinx, so please read and follow these Instructions for the doc strings. In addition, you can take a look at the following example file. Helpful hints on top of that:r"""<- this r makes me a raw string, thus '\' has no special meaning. Otherwise you would need to escape backslashes, e.g. in math formulas. You can include cross references to classes, methods, functions, modules like :class:`~tenpy.linalg.np_conserved.Array`, :meth:`~tenpy.linalg.np_conserved.Array.to_ndarray`, :func:`tenpy.tools.math.toiterable`, :mod:`tenpy.linalg.np_conserved`. The ~ in the beginning makes only the last part of the name appear in the generated documentation. Documents of the userguide can be referenced with :doc:`/intro_npc` even from inside the doc-strings. You can also cross-link to other documentations, e.g. :class:`numpy.ndarray`, :func`scipy.linalg.svd` and :mod: will work. Moreover, you can link to github issues, arXiv papers, dois, and topics in the community forum with e.g. :issue:`5`, :arxiv:`1805.00055`, :doi:`10.1000/1` and :forum:`3`. Write inline formulas as :math:`H |\Psi\rangle = E |\Psi\rangle` or displayed equations as .. math :: e^{i\pi} + 1 = 0 In doc-strings, math can only be used in the Notes section. To refer to variables within math, use `\mathtt{varname}`. .. todo :: This block can describe things which need to be done and is automatically included in a section of :doc:`todo`. """
Use relative imports within TeNPy. Example:
from ..linalg import np_conserved as npc
Use the python package pytest for testing. Run it simply with
pytest
in tests/. You should make sure that all tests run through, before yougit push
back into the public repo. Long-running tests are marked with the attribute slow; for a quick check you can also runpytest -m "not slow"
.Reversely, if you write new functions, please also include suitable tests!
During development, you might introduce
# TODO
comments. But also try to remove them again later! If you’re not 100% sure that you will remove it soon, please add a doc-string with a.. todo ::
block, such that we can keep track of it as explained in the previous point.Unfinished functions should
raise NotImplementedError()
.if you want to try out new things in temporary files: any folder named
playground
is ignored by git.
Thank You for helping with the development!
Bulding the documentation¶
You can use Sphinx to generate the full documentation in various formats (including HTML or PDF) yourself, as described in the following. First, install Sphinx and the extension numpydoc with:
pip install --upgrade sphinx numpydoc
Afterwards, simply go to the folder doc/ and run the following command:
make html
This should generate the html documentation in the folder doc/sphinx_build/html.
Open this folder (or to be precise: the file index.html in it) in your webbroser
and enjoy this and other documentation beautifully rendered, with cross links, math formulas
and even a search function.
Other output formats are available as other make targets, e.g., make latexpdf
.
Note
Building the documentation with sphinx requires loading the modules.
Thus make sure that the folder tenpy is included in your $PYTHONPATH
,
as described in doc/INSTALL.rst.