From 586ceeade5385589bb83530df566ea788e23d18b Mon Sep 17 00:00:00 2001 From: Ashley Scillitoe Date: Tue, 6 Sep 2022 09:19:19 +0100 Subject: [PATCH] Update CONTRIBUTING.md (#595) Expand guidance on docstrings for classes. --- CONTRIBUTING.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 28d15a0fc..7c8c3e7d0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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, @@ -104,4 +110,4 @@ replaced with an instance of the MissingDependency class. For example: ... ``` - Developers can use `make repl tox-env=` to run a python REPL with the specified optional dependency -installed. This is to allow manual testing. \ No newline at end of file +installed. This is to allow manual testing.