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:

minfloat

minimum value

maxfloat

maximum value

numinteger

number of log spaced bins

Returns:

outarray

log-spaced bins from min to max in a numpy array

Other Parameters:

kwargsdict

additional keywords passed into matplotlib.dates.num2date

See also

geomspace

linspace

Notes

This function works on both numbers and datetime objects. Not leapsecond aware.

Examples

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