-
Notifications
You must be signed in to change notification settings - Fork 1
Docstring Conventions
The following guidelines and templates must be followed in order for Sphinx to properly auto-document your Quicklook code. Sphinx uses a markup language called 'reStructuredText', which is very similar to the markup used for this wiki. It has the advantages of keeping the markup nonintrusive (so to keep the docstring readable in a text editor) and it is simple to learn. We will try to avoid Sphinx directives (e.g., .. dothisthing::) because they are not very readable in a text editor. Instead, we use a mix of Astropy's documentation guidelines (http://docs.astropy.org/en/add-mpl-to-rtd-pip-req/development/docguide.html), the Google Python Style Guide (http://google-styleguide.googlecode.com/svn/trunk/pyguide.html?showone=Comments#Comments), and some of our own preferences.
The reStructuredText markup will play nice as long as you keep the following rules:
- Use three double quotes to enclose a docstring.
- Keep length of lines under 72 characters.
- Indent with four spaces.
- Pay attention to the blank lines in the formatting templates. You will need to put blank lines between section titles, before code examples, etc.
- All document scripts must be protected by the condition
if __name__ == '__main__': - To indicate a file name or directory name, enclose in two right quotes (found on the '~' key!),
``file.txt`` and ``directory``
- To indicate a code example, use three right arrows,
>>> example_output = function-name(variable) - To cross-reference a function,
:func:`function-name`
- To cross-reference a module,
:mod:`module-name`
- You can use the Note and Warning directives, but sparingly:
.. note:: note textand.. warning:: warning text
Some reStructuredText examples: http://docutils.sourceforge.net/docs/user/rst/quickref.html
The following are the templates you must use on your docstrings if you want your code to be included in the Quicklook documentation website. At minimum, all module docstrings must contain a summary and authors section. All function and method docstrings must contain a summary and Parameters, Returns, and Outputs sections; write "nothing" in those sections when appropriate, but they must be included. Class docstrings are the same as functions and methods', except they do not have Returns or Outputs sections. Optional sections are noted in the templates below, and they should be included in your docstring when possible.
"""One line summary.
(optional) Longer summery if you need it. Keep all docstring rows to 72 characters.
Authors:
This is a chronological (newest first) listing of programmers who have contributed to or taken sufficient
ownership of this module that they can be contacted for help. When a person should be added to this list
is up to the discretion of the programmer. Date should be the date they first contributed.
First Last, Month, Year
First Last, Month, Year
(optional) Use:
If this module can be executed from the command line explain how to use it. e.g.:
cd into this_directory containing these_files.
>>> python example.py
(optional) Outputs:
If there are any outputs from running this module explain them. e.g.:
Text file. ``example.txt``.
(optional) Dependencies:
Known module version requirements that are not backwards compatible
Unusual external module dependencies (e.g. pyidl)
(optional) History:
This is best used only to document changes made to the code before it was put on GitLab.
(optional) Notes:
Any other helpful information you want to give.
(optional) References:
ISR numbers, urls, etc.
"""
"""One line summary.
(optional) Longer summery if you need it. Keep all docstring rows to 72 characters.
Parameters:
input1 : int
Description of input1.
input2 : list of strings
Description of input2.
If nothing is returned say "nothing" not "None" which is a python keyword, i.e. you could return a None.
Returns:
output1 : list of strings
Description of output1.
If nothing is returned say "nothing" not "None" which is a python keyword, i.e. you could return a None.
Outputs:
Considered an "output" if it is not a ``return``, but rather something generated, such as a plot or text file. For example,
Text file of these items. ``example.txt``
If nothing is returned say "nothing" not "None" which is a python keyword, i.e. you could return a None.
(optional) Notes:
Any other helpful information you want to give.
(optional) References:
Any urls, etc.
(optional) Examples:
An example call of the function.
>>> output_list = example(input1 = 111, input2 = ['a', 'b', 'c'])
"""
"""One line summary.
(optional) Longer summery if you need it. Keep all docstring rows to 72 characters.
Parameters:
input1 : int
Description of input1.
input2 : list of strings
Description of input2.
If nothing is returned say "nothing" not "None" which is a python keyword, i.e. you could return a None.
(optional) Notes:
Any other helpful information you want to give.
(optional) References:
Any urls, etc.
(optional) Examples:
An example call of the class.
"""
"""One line summary.
(optional) Longer summery if you need it. Keep all docstring rows to 72 characters.
Parameters:
input1 : int
Description of input1.
input2 : list of strings
Description of input2.
If nothing is returned say "nothing" not "None" which is a python keyword, i.e. you could return a None.
Returns:
output1 : list of strings
Description of output1.
If nothing is returned say "nothing" not "None" which is a python keyword, i.e. you could return a None.
Outputs:
Considered an "output" if it is not a ``return``, but rather something generated, such as a plot or text file. For example,
Text file of these items. ``example.txt``
If nothing is returned say "nothing" not "None" which is a python keyword, i.e. you could return a None.
(optional) Notes:
Any other helpful information you want to give.
(optional) References:
Any urls, etc.
(optional) Examples:
An example call of the method.
"""