# Documentation Standard

SpacePy aims to be a high quality product, and as such we (the SpacePy Team) encourage a a high degree of uniformity in the documentation across included modules. If you are contributing to SpacePy, or hope to, please take the time to make your code compliant with the documentation standard.

SpacePy uses Sphinx to generate its documentation. This allows most of the documentation to be built from docstrings in the code, with additional information being provided in reStructured Text files. This allows easy generation of high-quality, searchable HTML documentation.

In addition to Sphinx, SpacePy uses the following extensions:
  - ‘sphinx.ext.autodoc’
  - ‘sphinx.ext.doctest’‘
  - ‘sphinx.ext.intersphinx’
  - ‘sphinx.ext.todo’
  - ‘sphinx.ext.imgmath’ (falls back to ‘sphinx.ext.pngmath’ if imgmath is not available)
  - ‘sphinx.ext.ifconfig’
  - ‘sphinx.ext.viewcode’
  - ‘numpydoc’
  - ‘sphinx.ext.inheritance_diagram’
  - ‘sphinx.ext.autosummary’
  - ‘sphinx.ext.extlinks’

## So what do I need to do in my code?

Since we are using the ‘numpydoc’ extension there are fixed headings that may appear in your documentation block. There are a few things to note: * No other headings can appear in your docstrings * Most reStructuredText commands cannot appear in your docstrings either (e.g. .. Note:) * Since ‘numpydoc’ is not well documented, the best way of finding out what you can do in your docstrings is to look at the source for the SpacePy documentation or the numpy documentation.

### Allowed headings

Always use
  - Parameters
  - Returns
Use as needed
  - Attributes
  - Raises
  - Warns
  - Other Parameters
  - See Also
  - Notes
  - Warnings
  - References
  - Examples
  - Methods
No need to use
  - Summary
  - Extended Summary
  - index
Do not use
  - Signature
Examples
  - Use them, but they must be fully stand alone; the user should be able to type the exact code in the example and it should work as shown (doctest can help with this)

## Function Example

This code from toolbox shows what a function should look like in your code

>     def logspace(min, max, num, **kwargs):
>         """
>         Returns log spaced bins.  Same as numpy logspace except the min and max are the ,min and max
>         not log10(min) and log10(max)

>         Parameters
>         ==========
>         min : float
>             minimum value
>         max : float
>             maximum value
>         num : integer
>             number of log spaced bins

>         Other Parameters
>         ================
>         kwargs : dict
>             additional keywords passed into matplotlib.dates.num2date

>         Returns
>         =======
>         out : array
>             log spaced bins from min to max in a numpy array

>         Notes
>         =====
>         This function works on both numbers and datetime objects

>         Examples
>         ========
>         >>> import spacepy.toolbox as tb
>         >>> tb.logspace(1, 100, 5)
>         array([   1.        ,    3.16227766,   10.        ,   31.6227766 ,  100.        ])
>         """
>         from numpy import logspace, log10
>         if isinstance(min, datetime.datetime):
>             from matplotlib.dates import date2num, num2date
>             return num2date(logspace(log10(date2num(min)), log10(date2num(max)), num, **kwargs))
>         else:
>             return logspace(log10(min), log10(max), num, **kwargs)

Which then renders as:

> `spacepy.toolbox.``logspace`(min, max, num, **kwargs)

>   Returns log-spaced bins. Same as numpy.logspace except the min and max are the min and max not log10(min) and log10(max)

>   Parameters: | min : float minimum value max : float maximum value num : integer number of log spaced bins
>   Returns: | out : array log-spaced bins from min to max in a numpy array
>   Other Parameters:
>   | kwargs : dict additional keywords passed into matplotlib.dates.num2date

>   See also

>   `geomspace`, `linspace`

>   Notes

>   This function works on both numbers and datetime objects

>   Examples

>       >>> import spacepy.toolbox as tb
>       >>> tb.logspace(1, 100, 5)
>       array([   1.        ,    3.16227766,   10.        ,   31.6227766 ,  100.        ])