Skip to content

Latest commit

 

History

History
88 lines (66 loc) · 5.23 KB

guidelines.rst

File metadata and controls

88 lines (66 loc) · 5.23 KB
Raw

Coding Guidelines

To keep consistency, we ask you to comply with the following guidelines for contributions. However, these are just guidelines - it still helps if you contribute something, even if doesn't follow these rules ;-)

  • Use a code style based on 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 command yapf -i some/file (-i for "in place"). We run yapf on a regular basis on the github main branch. If your branch diverged, it might help to run yapf before merging.

  • Every function/class/module should be documented by its doc-string, see 257. We auto-format the doc-strings with docformatter on a regular basis.

    Additional documentation for the user guide is in the folder doc/.

    The documentation uses reStructuredText. If you are new to reStructuredText, read this introduction. We use the numpy style for doc-strings (with the napoleon extension to sphinx). You can read abouth them in 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`.

Citations from the literature list can be cited as :cite:`white1992` using the bibtex key.

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 you git push back into the public repo. Long-running tests are marked with the attribute slow; for a quick check you can also run pytest -m "not slow".

    We have set up github actions to automatically run the tests.

  • 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.

    Unfinished functions should raise NotImplementedError().

  • Summarize the changes you have made in the Changelog under /changelog/latest.
  • If you want to try out new things in temporary files: any folder named playground is ignored by git.
  • If you add a new toycode or example: add a reference to include it in the documentation.
  • We've created a sphinx extensions for documenting config-option dictionaries. If a class takes a dictionary of options, we usually call it options, convert it to a ~tenpy.tools.params.Config at the very beginning of the __init__ with ~tenpy.tools.params.asConfig, save it as self.options, and document it in the class doc-string with a .. cfg:config :: directive. The name of the config should usually be the class-name (if that is sufficiently unique), or for algorithms directly the common name of the algorithm, e.g. "DMRG"; use the same name for the use the same name for the documentation of the .. cfg:config :: directive as for the ~tenpy.tools.params.Config class instance. Attributes which are simply read-out options should be documented by just referencing the options with the :cfg:option:`configname.optionname` role.