diff --git a/Makefile b/Makefile
index deafea9..f298351 100644
--- a/Makefile
+++ b/Makefile
@@ -53,8 +53,8 @@ dist:
examples: PYTHONPATH = .
examples:
PYTHONPATH=.
- bin/yaml2rst examples/main.yml examples/main.rst
- rst2html --stylesheet=examples/demo.css examples/main.rst > examples/main.html
+ bin/yaml2rst examples/main.yml examples/main.rst --strip-regex '\s*(:?\[{3}|\]{3})\d?$$'
+ rst2html --stylesheet=examples/demo.css examples/main.rst | grep --invert-match --fixed-strings ' examples/main.html
rst2html --stylesheet=examples/demo.css tests/patternsTest.rst > tests/patternsTest.html
#-- interaction with PyPI
diff --git a/README.rst b/README.rst
index e344f3a..3974832 100644
--- a/README.rst
+++ b/README.rst
@@ -21,14 +21,19 @@ allows to process the YAML file directly without any pre-processing.
Usage::
- yaml2rst [-h] infile outfile
+ yaml2rst [-h] [--strip-regex regex] infile outfile
positional arguments:
- infile YAML-file to read (`-` for stdin)
- outfile rst-file to write (`-` for stdout)
+ infile YAML-file to read (`-` for stdin)
+ outfile rst-file to write (`-` for stdout)
optional arguments:
- -h, --help show this help message and exit
+ -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
@@ -43,6 +48,10 @@ 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
-------------
diff --git a/bin/yaml2rst b/bin/yaml2rst
index ff669c9..16344fb 100755
--- a/bin/yaml2rst
+++ b/bin/yaml2rst
@@ -32,7 +32,7 @@ import argparse
import sys
-def main(infilename, outfilename):
+def main(infilename, outfilename, strip_regex):
if infilename == '-':
infh = sys.stdin
else:
@@ -41,7 +41,7 @@ def main(infilename, outfilename):
outfh = sys.stdout
else:
outfh = open(outfilename, "w")
- for l in yaml2rst.convert(infh.readlines()):
+ for l in yaml2rst.convert(infh.readlines(), strip_regex):
print(l.rstrip(), file=outfh)
@@ -50,5 +50,10 @@ parser.add_argument('infilename', metavar='infile',
help="YAML-file to read (`-` for stdin)")
parser.add_argument('outfilename', metavar='outfile',
help="rst-file to write (`-` for stdout)")
+parser.add_argument('--strip-regex', metavar='regex',
+ help="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.")
args = parser.parse_args()
main(**vars(args))
diff --git a/docs/fold-markers.rst b/docs/fold-markers.rst
new file mode 100644
index 0000000..f258744
--- /dev/null
+++ b/docs/fold-markers.rst
@@ -0,0 +1,101 @@
+==========================
+Folding marks support
+==========================
+
+Folding marks in text editors like Vim can be quite helpful when you are used to
+them. One common way to fold different sections of your file is to use a fold
+marker. The thing is that you probably don’t want your fold markers ending up
+in the rendered documentation.
+
+So to use folds in your files, you basally have two options:
+
+#. Use reStructuredText comments for fold markers. Example:
+
+ .. code:: yaml
+
+ ---
+ # .. vim: foldmarker=[[[,]]]:foldmethod=marker
+
+ # .. contents:: Sections
+ # :local:
+
+ # .. First heading [[[
+ #
+ # -----------------
+ # First heading
+ # -----------------
+
+ # .. envvar:: example__list
+ #
+ # Some text describing this list.
+ example__list:
+ - 'Something'
+ - 'Something'
+
+ # .. ]]]
+
+ # .. Second heading [[[1
+ #
+ # ------------------
+ # Second heading
+ # ------------------
+
+#. Append your fold markers directly after reStructuredText headings. Example:
+
+ .. code:: yaml
+
+ ---
+ # .. vim: foldmarker=[[[,]]]:foldmethod=marker
+
+ # .. contents:: Sections
+ # :local:
+
+ # First heading [[[
+ # -------------
+
+ # .. envvar:: example__list
+ #
+ # Some text describing this list.
+ example__list:
+ - 'Something'
+ - 'Something'
+
+ # .. ]]]
+
+ # Second heading [[[1
+ # --------------
+ #
+
+Both variants have their pros and cons and both are supported by `yaml2rst`, so
+you can choose.
+
+Advantages of using reStructuredText comments for fold markers:
+
+* It works out of the box. You will not need to do anything extra as it only
+ depends on reStructuredText comments for the fold markers.
+ (For this, the ``--strip-regex`` command line option is not required.)
+
+* Section "overlines" don’t come in the way when moving folds around. This can
+ be an advantage when you are already using them.
+
+Advantages of appending your fold markers directly after reStructuredText headings:
+
+* No redundancy. (Don't repeat yourself)
+
+Because the "Don't repeat yourself" argument is actually quantifiable and has
+an impact on your ability to maintain your files it should be preferred when
+starting freshly. The pro arguments for fold markers in reStructuredText
+comments are just style questions.
+
+Which fold marker to use
+------------------------
+
+Now a short hash up regarding which fold markers to use.
+
+* ``{{{`` is the Vim default. Has the disadvantage that it might get in the way
+ with your syntax highlighting. However, '{{{' is not expected to be usually
+ found anywhere else in Ansible/YAML/Jinja.
+
+* ``(((`` is more likely to appear in Ansible/YAML/Jinja.
+
+* ``[[[`` is not expected to appear in Ansible/YAML/Jinja. Current recommendation.
diff --git a/examples/main.html b/examples/main.html
index 35e89be..9363a0d 100644
--- a/examples/main.html
+++ b/examples/main.html
@@ -3,7 +3,6 @@
-
collectd