QuartoPyDoc is a fork of quartodoc, created by Michael Chow at Posit but no longer maintained. Only the name of the distribution differs: you still import quartodoc, still run quartodoc build, and still configure a quartodoc: section in your _quarto.yml. For what this fork adds on top, see differences from quartodoc.

This fork is not intended for widespread use and should be considered alpha at best; it may change arbitrarily and is unlikely to be maintained long term. For Posit’s more modern document generation package that is a successor to quartodoc, see Great Docs. Eventually, anything of value from QuartoPyDoc will likely be merged into Great Docs.

Installation

python -m pip install quartopydoc

or from GitHub:

python -m pip install git+https://github.com/sciris/quartopydoc.git

Note that the package is installed as quartopydoc, but imported as quartodoc.

Important: if you haven't already, you'll need to install Quarto. We recommend the Sciris fork, which has improvements including parallel processing and skipping broken notebooks.

Differences from quartodoc

Everything documented for quartodoc still applies. On top of it, quartopydoc adds:

The qpyd and qpynb commands. Where quartodoc build generates your API reference pages, qpyd wraps the whole docs lifecycle — pre-render builds, rendering, previewing, publishing, and scaffolding a new docs folder — and qpynb runs, checks, converts, and cleans notebooks in parallel. See the qpyd CLI.

contents: auto. Document every public submodule of a package without listing them out, as shown above. Private modules and test modules are skipped.

griffe 2.x. quartopydoc requires griffe 2.0 or later, and tracks its current API.

qd.get_version() and qd.get_attr(). Read the documented package's version, or any other literal module-level constant (e.g. __versiondate__), from its source without importing it, for use in _variables.py. import quartodoc itself is also fast now, since the rest of the API is imported on first use.

A faster interlinks filter. The interlinks Quarto filter looks objects up by name instead of scanning every inventory for each link, and caches the merged inventories (in the project's .quarto/interlinks folder) instead of decoding them on every page. With large inventories (e.g. Python, NumPy and pandas), this saves a second or more per rendered page.

Note: installing both quartopydoc and quartodoc into the same environment will conflict, since both provide the quartodoc package and the quartodoc command. All quartodoc functionality is available from quartopydoc.

---

The rest of this readme is quartodoc's original (except for the install instructions).

quartodoc lets you quickly generate Python package API reference documentation using Markdown and Quarto. It 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.

Basic use

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:
  - reference/_sidebar.yml

# tell quarto to read the generated styles
format:
  html:
    css:
      - reference/_styles-quartodoc.css

quartodoc:
  # the name used to import the package you want to create reference docs for
  package: quartodoc

  # write sidebar and style data
  sidebar: reference/_sidebar.yml
  css: reference/_styles-quartodoc.css

  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

Rebuilding site

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

Looking up objects

Generating API reference docs for Python objects involves two pieces of configuration:

1. the package name.
2. 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.

Instead of listing them out, you can set contents: auto to document every public submodule of the package:

quartodoc:
  package: quartodoc
  sections:
    - title: All modules
      desc: ""
      contents: auto

Learning more

Go to the next page to learn how to configure quartodoc sites, or check out these handy pages:

• The qpyd CLI: building, previewing, and publishing a site, and managing notebooks.
• 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.