API Documentation #120

cmichelenstrofer · 2022-07-25T16:32:16Z

cmichelenstrofer
Jul 25, 2022
Maintainer

Always use for both inputs and outputs
As general as possible for inputs, as specific as possible in outputs. E.g. Mapping[]->dict[], Iterable[]->list[], etc.
Use Union instead of the newer | since it doesn't compile right.
Use the type aliases defined at the top of core.py. Add more as needed. Modify the list of aliases in conf.py and source_code.rst.
If function signature with in/out typehints does not fit in a single line (<=79 characters): put each input variable in a new line (single, standard tab), the closing parenthesis and output type hint in a new line aligned with the "def" statement. Use a trailing comma after the last parameter.

72 characters max line length
One sentence summary, in command format (e.g. "Do X" not "Does X").
Optional 1+ paragraphs of additional details
"Parameters" section: do not include the type (or the ":"); it will be added from the type hints
"Results" section: only if there is more than one output.. If only one output then document it in the details paragraphs. Will not compile correctly with one single variable in the Results. Exception (class static methods?).
"Examples" section, if included, must come before "Parameters"
"Raises" if there are any error checking.
"Notes" section is for additional details about the function/algorithm. For highlighted notes/warnings in other sections use :note: directive
"See Also" section include the name and description of other function in the module. If you include functions not in the module it will not compile correctly (check that the compiled html has links to these functions).
Emphasis: Use * for emphasis, ** for bold, :math: directive for math, etc. See the Sphinx reStructuredText document. Do not use backquotes without a specific directive.
Use :python: directive for code (defined in the conf.py file)
Summary sentence variable descriptions (in parameters, returns, see also, raises) start with upper case and end with period. No initial space for the summary sentence.