---
title: 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.

# 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](https://numpydoc.readthedocs.io/en/latest/format.html). 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](https://docs.python.org/3/library/typing.html).
Please make an effort to accurately annotate public functions/classes/methods.

Here is an example:

```{python}
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](https://docs.python.org/3/library/doctest.html) syntax as above, or
[quarto code blocks](https://quarto.org/docs/output-formats/html-code.html)
can be used directly. The latter gives more control over outputs and display options.

# Generating Documentation

DASCore's documentation is built with [quarto](https://quarto.org/). In order to build the documentation, you
must first [install DASCore in development mode](dev_install.qmd) then
[install quarto](https://quarto.org/docs/get-started/) and [install panflute](http://scorreia.com/software/panflute/).

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

```bash
python scripts/build_api_docs.py
```

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

```bash
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:

```bash
quarto preview docs
```

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

This can be used in both docstrings and the 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](https://quarto.org/docs/authoring/footnotes-and-citations.html#sec-citations).

Citing @lindsey2021fiber or [@lindsey2021fiber] 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}
$${#eq-rotations}

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 @eq-rotations is referenced by `@eq-rotations`.

# Additional Tips

For more information about figure alignment, code blocks, formatting, etc. checkout the
excellent [quarto docs](https://quarto.org/).
