Update CONTRIBUTING.md with guidance on class docstrings (#743)

Ashley Scillitoe · web-flow · commit fd0dcb6db189 · 2022-09-06T11:16:19.000+01:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -58,8 +58,14 @@ mypy alibi
 ## 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.
 
 #### Conventions
 
@@ -237,4 +243,4 @@ Checklist to run through before a PR is considered complete:
  - [Documentation](#building-documentation) is built locally and checked for errors/warning in the build log and any issues in the final docs, including API docs.
  - For any new functionality or new examples, appropriate links are added (`README.md`, `doc/source/index.rst`, `doc/source/overview/getting_started.md`,`doc/source/overview/algorithms.md`, `doc/source/examples`), see [Documentation for alibi](doc/README.md) for more information.
  - For any changes to existing algorithms, run the example notebooks manually and check that everything still works as expected and there are no extensive warnings/outputs from dependencies.
- - Any changes to dependencies are reflected in the appropriate place (`setup.py` for runtime and optional dependencies, `requirements/dev.txt` for development dependencies and `requirements/doc.txt` for documentation dependencies).
+ - Any changes to dependencies are reflected in the appropriate place (`setup.py` for runtime and optional dependencies, `requirements/dev.txt` for development dependencies and `requirements/doc.txt` for documentation dependencies).
