quartodoc lets you quickly generate Python package API reference documentation using Markdown and Quarto. quartodoc is designed as an alternative to Sphinx.
Check out the below screencast for a walkthrough of creating a documentation site, or read on for instructions.
python -m pip install quartodoc
or from GitHub
python -m pip install git+https://github.com/machow/quartodoc.git
Install Quarto
If you haven’t already, you’ll need to install Quarto before you can use quartodoc.
Getting started with quartodoc takes two steps: configuring quartodoc, then generating documentation pages for your library.
You can configure quartodoc alongside the rest of your Quarto site in
the
_quarto.yml
file you are already using for Quarto. To configure
quartodoc,
you need to add a quartodoc
section to the top level your
_quarto.yml
file. Below is a minimal example of a configuration that
documents the quartodoc
package:
project:
type: website
# tell quarto to read the generated sidebar
metadata-files:
- _sidebar.yml
quartodoc:
# the name used to import the package you want to create reference docs for
package: quartodoc
# write sidebar data to this file
sidebar: _sidebar.yml
sections:
- title: Some functions
desc: Functions to inspect docstrings.
contents:
# the functions being documented in the package.
# you can refer to anything: class methods, modules, etc..
- get_object
- preview
Now that you have configured quartodoc, you can generate the reference API docs with the following command:
quartodoc build
This will create a reference/
directory with an index.qmd
and
documentation pages for listed functions, like get_object
and
preview
.
Finally, preview your website with quarto:
quarto preview
You can preview your quartodoc
site using the following commands:
First, watch for changes to the library you are documenting so that your docs will automatically re-generate:
quartodoc build --watch
Second, preview your site:
quarto preview
Generating API reference docs for Python objects involves two pieces of configuration:
- the package name.
- a list of objects for content.
quartodoc can look up a wide variety of objects, including functions, modules, classes, attributes, and methods:
quartodoc:
package: quartodoc
sections:
- title: Some section
desc: ""
contents:
- get_object # function: quartodoc.get_object
- ast.preview # submodule func: quartodoc.ast.preview
- MdRenderer # class: quartodoc.MdRenderer
- MdRenderer.render # method: quartodoc.MDRenderer.render
- renderers # module: quartodoc.renderers
The functions listed in contents
are assumed to be imported from the
package.
Go to the next page to learn how to configure quartodoc sites, or check out these handy pages:
- Examples page: sites using quartodoc.
- Tutorials page: screencasts of building a quartodoc site.
- Docstring issues and examples: common issues when formatting docstrings.
- Programming, the big picture: the nitty gritty of how quartodoc works, and how to extend it.