README.qmd

---
format: gfm
jupyter:
  jupytext:
    text_representation:
      extension: .qmd
      format_name: quarto
      format_version: '1.0'
      jupytext_version: 1.14.1
  kernelspec:
    display_name: Python 3 (ipykernel)
    language: python
    name: python3
---

# quartodoc

Generate python API documentation for quarto.

## Install

```
pip install quartodoc
```

Or for the latest changes:

```
python3 -m pip install -e git+https://github.com/machow/quartodoc.git#egg=quartodoc
```

## Basic use

### Render a docstring

```{python}
#| output: false

from quartodoc import get_function, MdRenderer

# get function object ---
f_obj = get_function("quartodoc", "get_function")

# render ---
renderer = MdRenderer(header_level = 1)
print(
    renderer.to_md(f_obj)
)
```


    # get_function

    `get_function(module: str, func_name: str, parser: str = 'numpy')`

    Fetch a function.

    ## Parameters

    | Name        | Type   | Description                | Default   |
    |-------------|--------|----------------------------|-----------|
    | `module`    | str    | A module name.             | required  |
    | `func_name` | str    | A function name.           | required  |
    | `parser`    | str    | A docstring parser to use. | `'numpy'` |

    ## Examples

    ```python
    >>> get_function("quartodoc", "get_function")
    <Function('get_function', ...
    ```

### Build an index page

```{python}
#| output: false

from quartodoc.autosummary import BuilderPkgdown

builder = BuilderPkgdown(
    [
        {"title": "first", "desc": "section 1", "contents": ["get_object", "get_function"]},
        {"title": "2nd", "desc": "section 2", "contents": ["MdRenderer"]}
    ],
    "quartodoc"
    )

print(
    builder.render_index()
)
    
```



## How it works

quartodoc consists of two pieces:

* **collection**: using the library [griffe](https://github.com/mkdocstrings/griffe) to statically
collect information about functions and classes in a program.
* **docstring parsing**: also handled by griffe, which breaks it into a tree structure.
* **docstring rendering**: use plum-dispatch on methods like MdRenderer.to_md to decide
  how to visit and render each piece of the tree (e.g. the examples section, a parameter, etc..).

Here is a quick example of how you can grab a function from griffe and walk through it.

```{python}
from griffe.loader import GriffeLoader
from griffe.docstrings.parsers import Parser

griffe = GriffeLoader(docstring_parser = Parser("numpy"))
mod = griffe.load_module("quartodoc")

f_obj = mod._modules_collection["quartodoc.get_function"]
```

```{python}
f_obj.name
```

```{python}
docstring = f_obj.docstring.parsed
docstring
```

Note that quartodoc's MdRenderer can be called on any part of the parsed docstring.

```{python}
from quartodoc import MdRenderer

renderer = MdRenderer()

print(
    renderer.to_md(docstring[1])
)
```