Metadata-Version: 2.1
Name: docdantic
Version: 0.3.0
Summary: A markdown plugin for generating docs from Pydantic models
Home-page: https://gitlab.com/emergentmethods/docdantic
License: MIT
Author: Tim Pogue
Author-email: tim@emergentmethods.ai
Requires-Python: >=3.11,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: markdown (>=3.3.7,<4.0.0)
Requires-Dist: pydantic (>=2.5.0,<3.0.0)
Requires-Dist: tabulate (>=0.9.0,<0.10.0)
Project-URL: Repository, https://gitlab.com/emergentmethods/docdantic
Description-Content-Type: text/markdown

# Docdantic

![Gitlab code coverage (specific job)](https://img.shields.io/gitlab/pipeline-coverage/emergentmethods/docdantic?branch=main&job_name=unit-tests&style=flat-square)
![GitLab Release (latest by SemVer)](https://img.shields.io/gitlab/v/release/emergentmethods/docdantic?style=flat-square)
![GitLab](https://img.shields.io/gitlab/license/emergentmethods/docdantic?style=flat-square)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/docdantic?style=flat-square)

Docdantic is a Python library that enables the automatic generation of Markdown documentation from Pydantic models. It works as an extension of the Markdown package, extracting model details and creating neat tables with model fields and their properties.


## Features

* Supports both Pydantic V1 and V2 models.
* Automatically generate tables of Pydantic model fields with their details (name, type, required, default).
* Supports nested Pydantic models.
* Configurable exclusion of specific fields from the documentation.


## Installation

```bash
pip install docdantic
```

## Usage

### Using the Docdantic Extension

To generate documentation directly from Markdown files, you can use the Docdantic extension. Simply include the `!docdantic: import.path.to.Model` directive in your Markdown text:

```markdown
# MyModel Reference

!docdantic: my_module.MyModel
```

Docdantic will replace the !docdantic directive with a table of model field details.

### Using Docdantic in Python Code

If you want to programmatically generate Markdown documentation from Pydantic v2 models, you can use Docdantic in your Python code. Here's an example:

```python
import markdown
from docdantic import Docdantic

markdown_text = "Here are the details of my model:\n\n!docdantic: your.model.path"
converted_text = markdown.markdown(markdown_text, extensions=[Docdantic()])

# `converted_text` will contain the Markdown text with the model documentation
```

You can include the `!docdantic: your.model.path` directive in your Markdown text as before, and the `markdown.markdown` method will process it using the Docdantic extension.

## Configuration

Docdantic allows you to exclude specific fields from the generated documentation by using the exclude configuration. You can provide a JSON object in the exclude field of the configuration to specify which fields to exclude. For example:

```markdown
!docdantic: my_module.MyModel
    {
        "exclude": {
            "MyModel": ["field1", "field2"]
        }
    }
```

In the example above, the fields `field1` and `field2` will be excluded from the documentation of the `MyModel` model. Notice the configuration has to be indented with 2-4 spaces or a tab.

## License

This project is licensed under the terms of the MIT license. See [LICENSE](LICENSE) for more details.
