Contributing Guide¶
Welcome to the filehandlers contributing guidelines! Please follow what is listed here to help keep the project simple, easy to maintain, and complete.
Style Guide¶
Code¶
When writing code, please follow PEP8 [1], the style guide written for any Python. One exception for this is our line length - PEP8 says 79 characters is the limit, but we have decided to extend that to a maximum of 100 characters per line. Also, wherever possible, please add Docstrings.
Docstrings¶
We mainly use normal reStructuredText Docstrings for filehandlers.
However, for elements that have more then one field - for example if
a function has the potential to throw multiple exceptions -
we use Google [2] and/or
NumPy [3] styled Docstrings.
These are later converted by the Sphinx extension napoleon
during
documentation builds.
Please add Docstrings to functions, classes, modules (at the top), exceptions
and enumerators.
If you add a class that is not covered by the documentation currently (e.x. you create
a method or class that is not in a method/class that has the :members:
autodoc method), you will need to add a field so autodoc knows the include the Docstring(s).
To do this, navigate to the API reference page and add this underneath all the other
classes/methods:
For classes/enumerators¶
,.. autoclass:: ClassName
,:members:
,:special-members: __init__
For functions¶
,.. autofunction:: function_name
For exceptions¶
,.. autoexception:: ExceptionName
Notes¶
- Make sure to remove the commas, they prevent autodoc from trying to add a method here on this page!
- You do not need to add module Docstrings to the API reference page.
Building the package¶
Simply run python setup.py sdist bdist_wheel
.
If you are on Linux/macOS, change python
to python3
.
The build shouldn’t be long. When it is complete, you can find the .tar.gz
and .whl
in the dist
directory.
[1] | Python Enhancement Proposal #8 |
[2] | Google Docstring Guide |
[3] | NumPy Docstring Guide |