Open geraintpalmer opened 6 years ago
@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:
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.
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.