Documentation

There are several levels of documentation in DASCore. These include: code comments (which are primarily for developers), docstrings (which are used to generate the API docs), and markdown documentation pages like this one which have a .qmd extension.

Code comments

Code comments are primarily for developers. They should describe useful information and not just restate obvious parts of the code. Consider refactoring with better named variables or smaller, well named functions if you find yourself making lots of these types of comments.

Don’t be afraid to make multi-line comments if needed.

Doc-Strings

Use numpy style docstrings. All public code (doesn’t start with a _) should have a “full” docstring but private code (starts with a _) can have an abbreviated docstring.

DASCore makes extensive use of Python 3’s type hints. Please make an effort to accurately annotate public functions/classes/methods.

Here is an example:

from __future__ import annotations

import dascore
from dascore.constants import PatchType

# example public Patch function
@dascore.patch_function()
def example_func(patch: PatchType, to_add: int | float | None = None) -> PatchType:
    """
    A simple, one line explanation of what this function does.

    Additional details which might be useful, and are not limited to one
    line. In fact, they might span several lines, especially if the author
    of the docstring tends to include more details than needed.

    Parameters
    ----------
    patch
        A description of this parameter
    to_add
        A description of this parameter

    Returns
    -------
    If needed, more information about what this function returns.
    You shouldn't simply specify the type here since that is already
    given by the type annotation. If the returned object is self-explanatory
    feel free to skip this section.

    Examples
    --------
    >>> # Examples are included in the doctest style
    >>> import dascore
    ... pa = dascore.get_example_patch()
    ...
    ... out = example_func(pa)
    """

# example private function
def _recombobulate(df, arg1, arg2):
    """
    A private function can have a simple (multi-line) snippet
    and doesn't need as much detail or type hinting as a public
    function.
    """

Examples in docstrings

Examples in docstrings can be done using the standard doctest syntax as above, or quarto code blocks can be used directly. The latter gives more control over outputs and display options.

You can also specify quarto html code block options using a “#|” type comment and add headings using “###”. For example:

def my_func():
    """
    Example function.

    Examples
    --------
    >>> #| code-fold: true
    >>> # This is a base example
    >>> print(1 + 2)
    >>> ### This is a sub-section
    >>> print("cool beans")
    """

would produce the following code in the examples section:

```{python}
#| code-fold: true
# This is a base example
print(1 + 2)
```
### This is a sub-section
```{python}
#| code-fold: true
print("cool beans")
```

Generating Documentation

DASCore’s documentation is built with quarto. In order to build the documentation, you must first install DASCore in development mode then install quarto.

Next, the automatic API documents are created with scripts/build_api_docs.py

python scripts/build_api_docs.py

Finally, the documentation can be built by calling quarto render on the docs folder:

quarto render docs

The newly generated html can then be accessed by double-clicking on the html index at docs/_site/index.html.

Conversely, you can also preview the documentation so changes are rendered in real time in the browser:

quarto preview docs

Warning

If you need to change the structure of the site, like adding a new section/subsection, the file to edit is scripts/_templates/_quarto.yml. Do not modify docs/_quarto.yml because it will be overwritten.

Cross references

Cross references provide a means of linking parts of the documentation to the API docs for specific modules, classes, functions, or methods. They work just like normal markdown links except the reference is a dascore object surrounded by backticks like so:

This is a link to DASCore's [Patch](`dascore.core.Patch`).

To link to qmd files in the documentation folder (eg from a docstring) the path relative to the docs folder can be used:

This is a link to [this qmd file](`docs/contributing/documentation.qmd`).

Cross references can be used in both docstrings and the qmd documentation pages.

Referencing publications

New references should be added to the references.bib file in the docs folder.

Then, publications can be referenced in standard pandoc style.

Citing Lindsey and Martin (2021) or (Lindsey and Martin 2021) is done like so:

Citing @lindsey2021fiber or [@lindsey2021fiber]

References then show up at the bottom of the page, or if the mouse pointer hovers over the link.

Equations

Equations use standard latex. In line equations (\(E=mc^2\)) are surrounded by a single dollar sign ($) like this: $E=mc^2$. Multiline comments start and end with double dollar signs ($$) and can be given a reference-able label. For example:

\[ \begin{array}{l} \sigma_{n} = \sigma_1 cos^2 \theta + \sigma_3 sin^2 \theta \\ \sigma_{p} = \sigma_1 sin^2 \theta + \sigma_3 cos^2 \theta \\ \tau = (\sigma_1 - \sigma_3) sin \theta cos \theta \end{array} \tag{1}\]

is generated by:

$$
\begin{array}{l}
\sigma_{n} = \sigma_1 cos^2 \theta + \sigma_3 sin^2 \theta \\
\sigma_{p} = \sigma_1 sin^2 \theta + \sigma_3 cos^2 \theta \\
\tau = (\sigma_1 - \sigma_3) sin \theta cos \theta
\end{array}
$${#eq-rotations}

and Equation 1 is referenced by @eq-rotations.

Additional Tips

For more information about figure alignment, code blocks, formatting, etc. checkout the excellent quarto docs.

References

Lindsey, Nathaniel J, and Eileen R Martin. 2021. “Fiber-Optic Seismology.” Annual Review of Earth and Planetary Sciences 49: 309–36.