Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/machow/quartodoc
Generate API documentation with quarto
https://github.com/machow/quartodoc
Last synced: 1 day ago
JSON representation
Generate API documentation with quarto
- Host: GitHub
- URL: https://github.com/machow/quartodoc
- Owner: machow
- License: mit
- Created: 2022-11-04T18:52:28.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-12-05T15:17:55.000Z (about 1 month ago)
- Last Synced: 2025-01-04T06:05:08.254Z (9 days ago)
- Language: Python
- Homepage: https://machow.github.io/quartodoc
- Size: 58.2 MB
- Stars: 192
- Watchers: 5
- Forks: 20
- Open Issues: 83
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-quarto - quartodoc - A Python module that lets you quickly generate Python package API reference documentation using Markdown and Quarto. (Libraries/Packages/Scripts)
README
# Overview
[](https://github.com/machow/quartodoc/actions/workflows/ci.yml)
**quartodoc** lets you quickly generate Python package API reference
documentation using Markdown and [Quarto](https://quarto.org). quartodoc
is designed as an alternative to
[Sphinx](https://www.sphinx-doc.org/en/master/).
Check out the below screencast for a walkthrough of creating a
documentation site, or read on for instructions.
## Installation
``` bash
python -m pip install quartodoc
```
or from GitHub
``` bash
python -m pip install git+https://github.com/machow/quartodoc.git
```
> **Install Quarto**
>
> If you haven’t already, you’ll need to [install
> Quarto](https://quarto.org/docs/get-started/) 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`](https://quarto.org/docs/projects/quarto-projects.html)
file you are already using for Quarto. To [configure
quartodoc](https://machow.github.io/quartodoc/get-started/basic-docs.html#site-configuration),
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:
``` yaml
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:
``` bash
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:
``` bash
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:
``` bash
quartodoc build --watch
```
Second, preview your site:
``` bash
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:
``` yaml
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](https://machow.github.io/quartodoc/get-started/basic-docs.html) to
learn how to configure quartodoc sites, or check out these handy pages:
- [Examples
page](https://machow.github.io/quartodoc/examples/index.html): sites
using quartodoc.
- [Tutorials
page](https://machow.github.io/quartodoc/tutorials/index.html):
screencasts of building a quartodoc site.
- [Docstring issues and
examples](https://machow.github.io/quartodoc/get-started/docstring-examples.html):
common issues when formatting docstrings.
- [Programming, the big
picture](https://machow.github.io/quartodoc/get-started/dev-big-picture.html):
the nitty gritty of how quartodoc works, and how to extend it.