How to generate auto-documentation for a Python package, using quarto and quartodoc.
We need to install Quarto onto your local machine. You can download, or install via homebrew (if you like that kind of thing):
brew install --cask quartoIf you use VS Code, you can also consider installing the Quarto Extension.
Make a copy of this template repo. Clone your copy onto your computer and navigate to it from the command line.
Setup virtual environment:
conda create -n quarto-env python=3.10
conda activate quarto-envInstall package dependencies:
pip install -r requirements.txt
pip install -r docs/requirements.txtSee "my_project" directory for an example Python package code.
With corresponding tests in the "test" directory.
We use the top-level "requirements.txt" file to list dependencies of our Python package, including pytest for running tests.
In the "_quarto.yml" config file, we specify in the quartodoc section that our site should display "references/index.qmd", which will act as the entrypoint into the package auto-documentation.
Use quartodoc to automatically generate docstring content into the "references" directory:
quartodoc build --config docs/_quarto.yml --verboseAfter the documentation pages have been generated, then we can preview and build the site.
Previewing the site (runs like a local webserver):
quarto preview docs/Rendering the site (writes local HTML files to the "docs/_build" directory, which is ignored from version control):
quarto render docs/ --verboseWe are using the "python-app.yml" workflow configuration file to run tests for the example python package code (see "test" directory).
We are using the "quarto-pages.yml" workflow configuration file to deploy the site to GitHub Pages when new commits are pushed to the main branch.
In order for this to work, you first need to configure your GitHub Pages repo settings to publish via GitHub Actions.