View source for PySPEDAS docstring format

== Example header comments ==

PySPEDAS uses NumPy style docstrings as header comments to document the purpose, parameters, return values, and example usage of PySPEDAS routines.
Here is an example including all the elements we want to have, for any routine users might be expected to call (or understand):

<syntaxhighlight lang="python">
def state(trange=['2007-03-23', '2007-03-24'],
          probe='c',
          level='l1',
          suffix='',
          get_support_data=False,
          varformat=None,
          exclude_format=None,
          varnames=[],
          downloadonly=False,
          notplot=False,
          no_update=False,
          time_clip=False,
          keep_spin=False):
    """
    This function loads THEMIS state data

    Parameters:
        trange: list of str
            time range of interest [starttime, endtime] with the format
            ['YYYY-MM-DD','YYYY-MM-DD'] or to specify more or less than a day
            ['YYYY-MM-DD/hh:mm:ss','YYYY-MM-DD/hh:mm:ss']
            Default: ['2007-03-23', '2007-03-24']

        probe: str or list of str
            Spacecraft probe letter(s) ('a', 'b', 'c', 'd' and/or 'e')
            Default: 'c'

        level: str
            Data type; Valid options: 'l1'
            Default: 'l1'

        suffix: str
            The tplot variable names will be given this suffix.  By default,
            no suffix is added.

        get_support_data: bool
            Data with an attribute "VAR_TYPE" with a value of "support_data"
            will be loaded into tplot.
            Default: False

        varformat: str
            The file variable formats to load into tplot.  Wildcard character
            "*" is accepted.  By default, all variables are loaded in.

        exclude_format: str
            If specified, CDF variables matching this pattern will not be processed.
            Wildcard character "*" is accepted.  By default, no variables are excluded.

        varnames: list of str
            List of variable names to load
            (if not specified, all data variables are loaded)

        downloadonly: bool
            Set this flag to download the CDF files, but not load them into
            tplot variables
            Default: false

        notplot: bool
            Return the data in hash tables instead of creating tplot variables
            Default: false

        no_update: bool
            If set, only load data from your local cache
            Default: false

        time_clip: bool
            Time clip the variables to exactly the range specified
            in the trange keyword
            Default: false

        keep_spin: bool
            If True, do not delete the spin model tplot variables after the spin models are built.
            

    Returns:
        List of tplot variables created.

    Example:
        >>> import pyspedas
        >>> pyspedas.themis.state(trange=['2007-03-23', '2007-03-24'], probe='a', varnames=['tha_pos_gse','tha_vel_gse'])
        ['tha_pos_gse', 'tha_vel_gse']

    """

</syntaxhighlight>

== One line description ==
The first line after the opening triple-quote should give a one-line description of what the routine does.  This is what will be displayed in the 'help' command.

== Parameters ==
Each parameter should be described, including the expected type (string, bool, list or array of <whatever>), the valid values (if it's a smallish set of strings), and default value (if defined).

== Return values ==
Amy return values should be described.

== Usage example ==
A simple example showing a typical usage of the routine.   Examples should be self-contained, including any imports or setup needed to call the routine being documented.  We prefer to "import pyspedas", then call the routine using its fully qualified name, to make it clear where it fits into the pyspedas namespace. It is OK to use defaults for some parameters, if that's how the user would normally call the routine.  In this case, we want to make the time range and probe explicit, while letting some of the lesser-used parameters go to the defaults.  

The chevron prefix ">>>" should be used to denote what the user is expected to write.  Any output expected from the call should follow, without the chevrons.   (There are tools that can pull examples out of docstrings and use them as tests, so following this format gives us more options for automated testing.)