quartodoc 0.7.6

Description:

quartodoc 0.7.6

Overview

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.






Installation
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.


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:
- _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

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:

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.
Learning more
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.