Ciw
Ciw copied to clipboard
CiwPython
Docstrings
Develop a system for writing docstrings that is comprehensive and will be of use to future developers, and for overwriting class methods for implementing behaviour.
Section in docs that use autodoc to show these docstrings.
@geraintpalmer and I are going to start implementing this over the coming weeks and will be using the following format:
def write_records_to_file(self, file_name, headers=True):
"""
Writes the data records for all individuals who have completed
at least one service to a csv file in the current directory.
Parameters
----------
file_name : str
The name of records file
headers : bool
Is the first line of the csv going to be the column labels or not? (True/False)
"""
In the case of class definitions there will be an Attributes section, and for methods/functions with outputs there will also be a Returns section explaining what to expect as an output.
Any differences to the norm set out in these docstrings will be detailed in the relevant 'mother' docstrings.
E.g. It will be written in exactnode.py that float should be replaced by Decimal where relevant in other docstrings.
Looks like numpy style (sounds good), this might be of interest: https://samnicholls.net/2016/06/15/how-to-sphinx-readthedocs/
If you go down the autodoc route be sure to include make html in your CI so that you'll be prewarned of contributions that break your documentation (I forget if you already have this).
Should be possible to incrementally check and update parts of the code:
- https://stackoverflow.com/questions/42123798/is-there-any-way-to-lint-a-python-file-to-check-for-numpy-documentation-style-ad
While one can always go into GitHub to read the docstrings, or call help, I also think that having an "API Documentation" section of the HTML documentation would be beneficial.