Docstring guide
About docstrings
A documentation string(docstring) is a string used to document a module, class, function or method, so users can get information about what it does and how to use it without needing to read and understand the implementation. See References for more information about how they are used in other projects.
Sphinx is used to extract and convert docstrings into documentation HTML.
Template Function/Method Docstring
def find_image_path(self,
mis_fp:Path|str,
update:bool=True
)->Path|None:
"""
Find, and optionally update, hdf5 filepaths.
Checks stored location. Checks mis filepath folder for matching name.
Parameters
----------
mis_fp:Path|str,
Filepath to MISProject, expected to be in the same folder as the hdf5 file.
update:bool=True
If true when a matching file is found it will replace `self.hdf5_filepath`.
Returns
-------
return_path : Path | None
If a matching path is found it is returned, else `None` is returned.
"""
Template Class Docstring
class MISImageFile():
"""
Access image data and information from an image file.
"""
Template Module Docstring
"""
Models for handling data organization, data access, and file I/O.
Includes `Protocol` models: `MISProject`, `MISImage`, and `MISRelation`.
"""
Sections
1. Short Summary
Single sentence description of what the object does.
2. Extended Summary
Additional details on what the object does. Excludes parameters or implementation notes. A blank line is left between short and extended summaries. Should include details on why the object is useful and its use cases.
3. Parameters
The details of the parameters go in this section. Generally, the pandas docstring guide for parameters should be followed.
4. Returns Or Yields
If a function or method returns(or yields) a value it should be document in this section. Generally, the pandas docstring guide for returns or yields should be followed.
5. Notes
This is an optional section for additional information about the object. This could include implementation notes or counter-intuitive behavior.
6. Examples
This section is for examples illustration the use of the object. Generally, the pandas docstring guide for examples should be followed.
Notes
Standard relation notation is from image a to image b.
References
This guide draws upon existing projects & documentation for direction including: