https://github.com/debops/yaml2rst
A Simple Tool and Python-Module for Documenting YAML Files
https://github.com/debops/yaml2rst
Last synced: about 1 year ago
JSON representation
A Simple Tool and Python-Module for Documenting YAML Files
- Host: GitHub
- URL: https://github.com/debops/yaml2rst
- Owner: debops
- License: gpl-3.0
- Created: 2015-02-09T13:01:01.000Z (over 11 years ago)
- Default Branch: develop
- Last Pushed: 2020-01-02T19:39:42.000Z (over 6 years ago)
- Last Synced: 2025-05-29T19:34:36.267Z (about 1 year ago)
- Language: Python
- Homepage:
- Size: 79.1 KB
- Stars: 18
- Watchers: 6
- Forks: 12
- Open Issues: 2
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGES.rst
- License: LICENSE
Awesome Lists containing this project
README
==========================
yaml2rst
==========================
--------------------------------------------------------------------------
A Simple Tool and Python-Module for Documenting YAML Files
--------------------------------------------------------------------------
:Author: Hartmut Goebel
:Copyright: 2015-2019 by Hartmut Goebel
:Licence: GNU General Public Licence v3 or later (GPLv3+)
This tool allows you writing documentation directly into YAML-files as
comments. These comments will then be converted to text and the YAML-code
goes into literal blocks.
This is some kind of `literate programming`, except that you do not
write code into your text, but text into your code. This difference
allows to process the YAML file directly without any pre-processing.
Usage::
yaml2rst [-h] [--strip-regex regex] infile outfile
positional arguments:
infile YAML-file to read (`-` for stdin)
outfile rst-file to write (`-` for stdout)
optional arguments:
-h, --help show this help message and exit
--strip-regex regex Regex which will remove everything it matches. Can be
used to remove fold markers from headings for example.
Example to strip out [[[,]]] fold markers:
'\s*(:?\[{3}|\]{3})\d?$'. Check the README for more
details.
How it works
----------------
This script takes all lines beginning with :literal:`#\ ` (and lines
consisting of only a ``#``) as text-lines. Everything else will be
treated as "code". The text-lines will get the :literal:`#\ ` removed
and the "code" will get spaces prepended.
Additionally at the start and at the end of a "code"-block, lines are
added as required by reStructuredText. Also at the begin of a
"code"-block, a ``::`` is added if required.
``--strip-regex`` can be used to remove matching characters from text-lines
when needed. Refer to documentation about
`Folding marks support `_ for details.
Examples
-------------
You can find example yaml-input, rst-output and generated html in the
examples directory. You may also view the generated html online at
https://rawgit.com/debops/yaml2rst/develop/examples/main.html.
Related Tools
---------------------
* `yaml4rst `_ is a
linting/checking/reformatting tool for YAML files documented with
inline RST which goes hand in hand with yaml2rst.
Maintainers
---------------------
`yaml2rst` was originally developed 2015 and maintained by Hartmut
Goebel. In 2019 the project moved to the `debops` project for which
`yaml2rst` was developed.
..
Local Variables:
mode: rst
ispell-local-dictionary: "american"
End: