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.

https://numpydoc.readthedocs.io/en/latest/format.html

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):
   """
   Load 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.
           Default: None

   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.
           Default: None (all variables are loaded)

   exclude_format : str
           If specified, CDF variables matching this pattern will not be processed.
           Wildcard character "*" is accepted.
           Default: None

   varnames : list of str
           List of variable names to load. If list is empty or unsoecified, all data variables are loaded
           Default: [] (all 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.
           Default: False

   Returns
   -------
   list of str
           List of tplot variables created.

   Example
   -------
       >>> import pyspedas
       >>> from pytplot import tplot
       >>> pyspedas.themis.state(trange=['2007-03-23', '2007-03-24'], probe='a', varnames=['tha_pos_gse','tha_vel_gse'])
       >>> tplot['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. For mission-specific load routines and other utilities, the mission name should appear in the one-line help (because other missions may have routines with similar names and usage). It seems there is a preference in the Python community to phrase this as an imperative ("Load THEMIS state data") rather than a description ("This routine loads THEMIS state data").

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.)