Common issues and examples

This page provides examples for commonly encountered situations (and some funky ones).

See the numpydoc sections guide for more information and examples.

Examples: using code blocks

Often, the Examples section of docstrings contain code examples.

The Examples section supports two formats for code examples:

• doctest syntax - code starts with >>>.
• markdown syntax - surrounding code with three backticks (```)
• quarto syntax - similar to markdown syntax (e.g. ```{python}), but will execute code in the docs.

Below is an example including each.

    Examples
    --------
    
    doctest syntax:
    
    >>> 1 + 1
    2
    
    markdown syntax:
    
    ```python
    1 + 1
    ```
    
    quarto syntax:
    
    ```{python}
    1 + 1
    ```

Note that different syntaxes are handled differently:

• doctest and markdown syntax: rendered without executing.
• quarto syntax: executed by quarto when you run commands like quarto render.

See the quarto documentation on code blocks for more detail.

Examples, etc..: the “s” matters

The numpydoc spec pluralizes section most names. If you leave off the “s”, then they may be misparsed.

For example, the docstring below erroneously has a “Return” section:

Return
------

some_name: int
    a description of the return result

In this case, the section won’t be parsed, but written directly into the doc page. This means that “Return” would show up as a level 2 header.

Here is a list of pluralized section names:

• Parameters
• Returns
• Yields
• Receives
• Other Parameters
• Raises
• Warns
• Warnings
• Notes
• References
• Examples

Returns: using type annotation

In order to use the return type annotation of a function, use the following syntax.

Returns
--------
:
    Some description of result

Below is a full example.

def f() -> int:
    """Some func

    Returns
    -------
    :
        A number
    """

See the numpydoc Returns specification for more on the general form of the Returns section.

Using interlinks in docstrings

quartodoc supports linking to functions using the interlinks quarto filter (and linking in general using quarto link syntax).

The code below shows an interlink, along with a regular quarto link.

def f():
    """A function.

    Interlinks filter:

    See [](`quartodoc.get_object`)

    Regular quarto link (to a page in your docs):

    See the [reference](/reference/index.qmd) page.
    """

Note

Linking to functions documented outside your package must be configured in the interlinks filter.

How do I document a class?

See this numpydoc page on documenting classes.

Below is a simple example of a class docstring.

class MyClass:
    """A great class.

    Parameters
    ----------
    a:
        Some parameter.

    Attributes
    ----------
    x:
        An integer
    """


    x: int = 1


    def __init__(self, a: str):
        self.a = a

Note these two important pieces:

• Document your __init__ method parameters on the class docstring.
• You can use an Attributes section in your docstring.