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

You can build the documentation pages locally to see how the new changes will look. First, make sure that you have created and activated an environment with simpeg installed in it. Then, navigate to the docs folder:

cd docs

And run the following to build the docs:

make html

Note

This command will build all documentation pages, including all the examples and tutorials. Running the examples might take considerable amount of time.

If you want to build the docs, but avoid running the examples, you can alternatively run:

make html-noplot

Serving the documentation locally

Once the documentation is built, you can view it using the following command (make sure you are in the docs directory):

make serve

It will automatically serve the docs and you can see them in your browser.

Alternatively, you can open your file manager and open the index.html file in the docs/_build/html folder.