Metadata-Version: 2.4
Name: sphinxcontrib-autoyaml
Version: 1.2.0
Summary: Sphinx autodoc extension for documenting YAML files from comments
Author-email: Jakub Pieńkowski <jakub+sphinxcontrib-autoyaml@jakski.name>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Documentation
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Sphinx>=3.5.1
Requires-Dist: ruamel.yaml>=0.16.12
Dynamic: license-file

# sphinxcontrib-autoyaml

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

This document:

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

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

would be turned into text:

```rst
enable_nginx

   Enable Nginx web server.

enable_varnish

   Enable Varnish caching proxy.
```

See `tests/examples/output/*.yml` and `tests/examples/output/*.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.:

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

Documenting single YAML file.

.. autoyaml:: some_yml_file.yml
```

## Options

```python
# Look for YAML files relatively to this directory.
autoyaml_root = ".."
# Character(s) which start a documentation comment.
autoyaml_doc_delimiter = "###"
# Comment start character(s).
autoyaml_comment = "#"
# Parse comments from nested structures n-levels deep.
autoyaml_level = 1
# Whether to use YAML SafeLoader
autoyaml_safe_loader = False
```

## Installing

Issue command:

```sh
pip install sphinxcontrib-autoyaml
```

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

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

## Caveats

### Mapping keys nested in sequences

Sequences are traversed as well, but they are not represented in output
documentation. This extension focuses only on documenting mapping keys. It means
that structure like this:

```yaml
key:
  ###
  # comment1
  - - inner_key1: value
      ###
      # comment2
      inner_key2: value
  ###
  # comment3
  - inner_key3: value
```

will be flattened, so it will appear as though inner keys exist directly under
`key`. Duplicated key documentation will be duplicated in output as well. See
`tests/examples/output/comment-in-nested-sequence.txt` and
`tests/examples/output/comment-in-nested-sequence.yml` to get a better
understanding how sequences are processed.

### Complex mapping keys

YAML allows for complex mapping keys like so:

```yaml
[1, 2]: value
```

These kind of keys won't be documented in output, because it's unclear how they
should be represented as a string.

### Flow-style entries

YAML allows writing complex data structures in single line like JSON.
Documentation is generated only for the first key in such entry, so this:

```yaml
###
# comment
key: {key1: value, key2: value, key3: value}
```

would yield documentation only for `key`.
