SpectroChemPy Docstring Guide

This guide explains how to write docstrings for SpectroChemPy. We follow the NumPy docstring convention with some SpectroChemPy-specific additions.

Docstring Format

SpectroChemPy uses numpydoc format for docstrings. Each docstring should contain:

1. A short summary (one line)

2. An extended description (optional)

3. Parameters section

4. Returns/Yields section

5. See Also section (optional)

6. Notes section (optional)

7. Examples section

Basic Rules

• Use triple double quotes """

• Start immediately after the quotes

• No blank lines before/after docstring

• Use backticks for code: parameter_name, NDDataset

• Link to classes/methods using :class:, :meth:, :func:

• End sections with periods

Example Structure

def baseline(self, method="rubberband", **kwargs):
    """
    Apply baseline correction to the dataset.

    Corrects baseline using the specified method.

    Parameters
    ----------
    method : {"rubberband", "polyfit", "asls"}, default "rubberband"
        Method to use for baseline correction.
    **kwargs
        Additional parameters passed to the correction method.

    Returns
    -------
    NDDataset
        Dataset with corrected baseline.

    See Also
    --------
    detrend : Remove linear trends.
    smooth : Apply smoothing filters.

    Examples
    --------
    >>> ds = scp.read("myfile.spg")
    >>> ds_corrected = ds.baseline()
    """
    // implementation

Parameter Documentation

Types should be:

• Built-in types: int, float, str, bool

• Container types: list of int, dict of {str: float}

• SpectroChemPy types: NDDataset, Coord

• NumPy types: numpy.ndarray, array-like

• Multiple types: int or float, str or None

For choices, list options in curly braces:

method : {"linear", "polynomial"}, default "linear"
axis : {0, 1, None}, default None

Examples Section

Examples should be:

1. Complete and runnable

2. As concise as possible

3. Show typical usage first

4. Written as doctest snippets

Always import SpectroChemPy as:

>>> import spectrochempy as scp

For plots, use the plot directive:

Examples
--------
.. plot::
    :context: close-figs

    >>> ds = scp.read("myfile.spg")
    >>> ds.plot()

See the numpydoc guide for more details.