Metadata-Version: 2.1
Name: quartodoc
Version: 0.7.0
Summary: Generate API documentation with Quarto.
Author-email: Michael Chow <michael.chow@posit.co>
License: MIT License
        
        Copyright (c) 2023 quartodoc authors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: homepage, https://machow.github.io/quartodoc
Project-URL: repository, https://github.com/machow/quartodoc
Project-URL: ci, https://github.com/machow/quartodoc/actions
Keywords: documentation,quarto
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click
Requires-Dist: griffe>=0.33
Requires-Dist: sphobjinv>=2.3.1
Requires-Dist: tabulate>=0.9.0
Requires-Dist: importlib-metadata>=5.1.0
Requires-Dist: importlib-resources>=5.10.2
Requires-Dist: pydantic
Requires-Dist: pyyaml
Requires-Dist: typing-extensions>=4.4.0
Requires-Dist: watchdog>=3.0.0
Requires-Dist: plum-dispatch<2.0.0; python_version < "3.10"
Requires-Dist: plum-dispatch>2.0.0; python_version >= "3.10"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: jupyterlab; extra == "dev"
Requires-Dist: jupytext; extra == "dev"
Requires-Dist: syrupy; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"

# Overview

[![CI](https://github.com/machow/quartodoc/actions/workflows/ci.yml/badge.svg)](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.

<p align="center">
<a href="https://www.loom.com/share/fb4eb736848e470b8409ba46b514e2ed">
<img src="https://cdn.loom.com/sessions/thumbnails/fb4eb736848e470b8409ba46b514e2ed-00001.gif" width="75%">
</a>
</p>

<br>

## Installation

``` bash
python -m pip install quartodoc
```

or from GitHub

``` bash
python -m pip install git+https://github.com/machow/quartodoc.git
```

<div>

> **Install Quarto**
>
> If you haven’t already, you’ll need to [install
> Quarto](https://quarto.org/docs/get-started/) before you can use
> quartodoc.

</div>

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