Documentation

Documentation helps others use your code! Please document new contributions. SimPEG tries to follow the numpydoc style of docstrings (check out the style guide). SimPEG then uses sphinx to build the documentation. When documenting a new class or function, please include a description (with math if it solves an equation), inputs, outputs and preferably a small example.

For example:

class WeightedLeastSquares(BaseComboRegularization):
    r"""Weighted least squares measure on model smallness and smoothness.

    L2 regularization with both smallness and smoothness (first order
    derivative) contributions.

    Parameters
    ----------
    mesh : discretize.base.BaseMesh
        The mesh on which the model parameters are defined. This is used
        for constructing difference operators for the smoothness terms.
    active_cells : array_like of bool or int, optional
        List of active cell indices, or a `mesh.n_cells` boolean array
        describing active cells.
    alpha_s : float, optional
        Smallness weight
    alpha_x, alpha_y, alpha_z : float or None, optional
        First order smoothness weights for the respective dimensions.
        `None` implies setting these weights using the `length_scale`
        parameters.
    alpha_xx, alpha_yy, alpha_zz : float, optional
        Second order smoothness weights for the respective dimensions.
    length_scale_x, length_scale_y, length_scale_z : float, optional
        First order smoothness length scales for the respective dimensions.
    mapping : SimPEG.maps.IdentityMap, optional
        A mapping to apply to the model before regularization.
    reference_model : array_like, optional
    reference_model_in_smooth : bool, optional
        Whether to include the reference model in the smoothness terms.
    weights : None, array_like, or dict or array_like, optional
        User defined weights. It is recommended to interact with weights using
        the `get_weights`, `set_weights` functionality.

    Notes
    -----
    The function defined here approximates:

    .. math::
        \phi_m(\mathbf{m}) = \alpha_s \| W_s (\mathbf{m} - \mathbf{m_{ref}} ) \|^2
        + \alpha_x \| W_x \frac{\partial}{\partial x} (\mathbf{m} - \mathbf{m_{ref}} ) \|^2
        + \alpha_y \| W_y \frac{\partial}{\partial y} (\mathbf{m} - \mathbf{m_{ref}} ) \|^2
        + \alpha_z \| W_z \frac{\partial}{\partial z} (\mathbf{m} - \mathbf{m_{ref}} ) \|^2

    Note if the key word argument `reference_model_in_smooth` is False, then mref is not
    included in the smoothness contribution.

    If length scales are used to set the smoothness weights, alphas are respectively set internally using:
    >>> alpha_x = (length_scale_x * min(mesh.edge_lengths)) ** 2
    """

Building the documentation

If you would like to see the documentation changes. In the repo’s root directory, enter the following in your terminal.

make all

Serving the documentation locally

Once the documentation is built. You can view it directly using the following command. This will automatically serve the docs and you can see them in your browser.

make serve