Documentation Instructions - Quarto and Quartodoc

[mdancho84]

Documentation Instructions

• Create package documentation (docstrings)
• Use Quarto and Quartodoc to build the Python package documentation

1. Create Package Documentation

The easiest way to create documentation fast is to use Mintlify Doc Writer for Python

IMPORTANT: Quartodoc uses Numpy Docstring Formatting

You can then highlight a function and select "Generate Docstring".

2. Use Quartodoc & Quarto to generate Package Documentation

Make sure Quarto and Quartodoc are installed.

• Quarto: https://quarto.org/
• Quartodoc: https://machow.github.io/quartodoc/get-started/overview.html

The main commands are:

# Change directory to /docs folder
cd docs 

# Build the documentation
quartodoc build

# Preview the website
quarto preview

You should now see a website on your localhost:

Making Tutorials

We will eventually need to make some tutorials and documentation. Will cover this later after we create the core timetk functions.

Publishing Changes

• You can just make a pull request with any changes. Once I merge I'll publish.
• The command is quarto publish gh-pages, which publishes to the gh-pages branch.

[mdancho84]

Example of NumPy Style Docstrings

def add_numbers(num1, num2):
    """
    Add two numbers together.
    
    This function takes two numbers, `num1` and `num2`, and returns their sum.
    The numbers can be either integers or floats.
    
    Parameters
    ----------
    num1 : int or float
        The first number to be added.
    num2 : int or float
        The second number to be added.
    
    Returns
    -------
    int or float
        The sum of `num1` and `num2`.
    
    Examples
    --------
    >>> add_numbers(2, 3)
    5
    >>> add_numbers(3.5, 5.5)
    9.0
    
    Notes
    -----
    This is a simple illustrative example and not intended for actual use.
    """
    return num1 + num2

[iskode]

Hi Matt, I've finished a fresh install on a mew environment. I've found that we need to install notebook before running quatro preview. I do know that it is obvious to have it in our environment as data scientist but just for the sake of specifiying the dependencies.

[machow]

Hey, if you run into any issues at all with quartodoc, don't hesitate to reach out. I'm always happy to clone repos and try building / debugging them, since I want to make sure the doc building process is as painless as possible!

[mdancho84]

@machow excellent work on Quartodoc. It's been a breeze to set up good looking and performant documentation.