Skip to main content

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.

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.


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 before you can use quartodoc.

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

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.

Learning more

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

Metadata

Release files for quartopydoc 0.13.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for quartopydoc 0.13.0
File Size Uploaded Provenance Actions
quartopydoc-0.13.0.tar.gz 830.5 kB Without provenance Details for quartopydoc-0.13.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for quartopydoc 0.13.0
File Interpreter ABI Platform Actions
quartopydoc-0.13.0-py3-none-any.whl Python 3 none any Details for quartopydoc-0.13.0-py3-none-any.whl

Total release size: 973.0 kB

Release files / quartopydoc-0.13.0.tar.gz

Download URL quartopydoc-0.13.0.tar.gz
Size 830.5 kB
Tags Source
SHA-256 checksum
How to use checksums
c1508b099d46c879d152001a6a8e669895083e58d07bd9fab8033af6ab74c0e4
BLAKE2b-256 checksum
How to use checksums
390266ade83f87b6bff8001c249ddfb5619927ee5a69aa9055540fb712156b64
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.9

Release files / quartopydoc-0.13.0-py3-none-any.whl

Download URL quartopydoc-0.13.0-py3-none-any.whl
Size 142.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ba9d5b662ad9f9b132284f081181cfc193033234d3bb9c4eea8a2481e0756d67
BLAKE2b-256 checksum
How to use checksums
34eb364c951212409d538010ad1e6d053ea519acdb33cfd7eb1926036eef3099
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.9

Security for quartopydoc 0.13.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page