Metadata-Version: 2.1
Name: sphinxcontrib-autoyaml
Version: 0.6.0
Summary: Sphinx autodoc extension for documenting YAML files from comments
Home-page: https://github.com/Jakski/sphinxcontrib-autoyaml
License: MIT
Author: Jakub Pieńkowski
Author-email: jakub+sphinxcontrib-autoyaml@jakski.name
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Documentation
Requires-Dist: Sphinx (>=3.5.1,<4.0.0)
Requires-Dist: ruamel.yaml (>=0.16.12,<0.17.0)
Project-URL: Repository, https://github.com/Jakski/sphinxcontrib-autoyaml
Description-Content-Type: text/markdown

# sphinxcontrib-autoyaml

This Sphinx autodoc extension documents YAML files from comments. Documentation
is returned as reST definitions, e.g.:

This document:

```
###
# Enable Nginx web server.
enable_nginx: true

###
# Enable Varnish caching proxy.
enable_varnish: true
```

would be turned into text:

```
enable_nginx

   Enable Nginx web server.

enable_varnish

   Enable Varnish caching proxy.
```

See `tests/examples/output/index.yml` and `tests/examples/output/index.txt` for
more examples.

`autoyaml` will take into account only comments which first line starts with
`autoyaml_doc_delimiter`.

## Usage

You can use `autoyaml` directive, where you want to extract comments
from YAML file, e.g.:

```
Some title
==========

Documenting single YAML file.

.. autoyaml:: some_yml_file.yml
```

## Options

Options available to use in your configuration:

- *autoyaml_root*(`..`)
  Look for YAML files relatively to this directory.
- *autoyaml_doc_delimiter*(`###`)
  Character(s) which start a documentation comment.
- *autoyaml_comment*(`#`)
  Comment start character(s).

## Installing

Issue command:

```
pip install sphinxcontrib-autoyaml
```

And add extension in your project's ``conf.py``:

```
extensions = ["sphinxcontrib.autoyaml"]
```

