Skip to content

Commit

Permalink
Update CONTRIBUTING.md (#595)
Browse files Browse the repository at this point in the history
Expand guidance on docstrings for classes.
  • Loading branch information
ascillitoe authored Sep 6, 2022
1 parent 0bbe586 commit 586ceea
Showing 1 changed file with 9 additions and 3 deletions.
12 changes: 9 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,14 @@ options are defined in `setup.cfg`.
## Docstrings
We adhere to the `numpy` style docstrings (https://numpydoc.readthedocs.io/en/stable/format.html)
with the exception of ommiting argument types in docstrings in favour of type hints in function
and class signatures. If you're using a `PyCharm`, you can configure this under
`File -> Settings -> Tools -> Python Integrated Tools -> Docstrings`.
and class signatures. If you use an IDE, you may be able to configure it to assist you with writing
docstrings in the correct format. For `PyCharm`, you can configure this under
`File -> Settings -> Tools -> Python Integrated Tools -> Docstrings`. For `Visual Studio Code`, you can obtain
docstring generator extensions from the [VisualStudio Marketplace](https://marketplace.visualstudio.com/).

When documenting Python classes, we adhere to the convention of including docstrings in their `__init__` method,
rather than as a class level docstring. Docstrings should only be included at the class-level if a class does
not posess an `__init__` method, for example because it is a static class.

## Building documentation
We use `sphinx` for building documentation. You can call `make build_docs` from the project root,
Expand Down Expand Up @@ -104,4 +110,4 @@ replaced with an instance of the MissingDependency class. For example:
...
```
- Developers can use `make repl tox-env=<tox-env-name>` to run a python REPL with the specified optional dependency
installed. This is to allow manual testing.
installed. This is to allow manual testing.

0 comments on commit 586ceea

Please sign in to comment.