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.

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.

An authorship badge. The authorship Quarto filter shows a page's authorship front matter (human and ai percentages and a note) as a badge at the top right, with the note on hover. Install it with quarto add sciris/quartopydoc (which also installs interlinks), add authorship to the project's filters, and give a page e.g. authorship: {human: 90, ai: 10, note: "Humans wrote everything, except some code examples"}. A rule for .authorship in the project's CSS overrides the badge's style.

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:

Metadata

Release files for quartopydoc 0.14.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.14.0
File Size Uploaded Provenance Actions
quartopydoc-0.14.0.tar.gz 833.1 kB Without provenance Details for quartopydoc-0.14.0.tar.gz

Built distribution (wheel)

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

Total release size: 976.6 kB

Release files / quartopydoc-0.14.0.tar.gz

Download URL quartopydoc-0.14.0.tar.gz
Size 833.1 kB
Tags Source
SHA-256 checksum
How to use checksums
fe759da5477dd89e4c0f9cd3ca304b5b6971f344a969dd5d48cf8d76e0b686ab
BLAKE2b-256 checksum
How to use checksums
248d2878ab8e13690e93f954fb8094c8ec4c1537af8142f360cf95e3716c76cb
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.14.0-py3-none-any.whl

Download URL quartopydoc-0.14.0-py3-none-any.whl
Size 143.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
71c6f4924ca374bce67c4dbfde725e4b3896c06027eefdff49b8d82c4f5cb305
BLAKE2b-256 checksum
How to use checksums
223980b111b61e4a602cb23f8a13c96036519b1f57e0193135bef9839c1d3985
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.14.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