Fold format: Documented decision process and outcome for the DebOps p…

…roject.

Related to: debops/docs#156

Makefile

@@ -53,7 +53,8 @@ dist:
 examples: PYTHONPATH = .
 examples:
 	PYTHONPATH=.
-	bin/yaml2rst examples/main.yml examples/main.rst --strip-regex '\s*(:?\[{3}|\]{3})\d?$$'
+	sed --regexp-extended 's/(\.\. )envvar(::)/\1note\2/;' examples/fold-markers-debops.yml examples/main.yml | bin/yaml2rst - examples/main.rst --strip-regex '\s*(:?\[{3}|\]{3})\d?$$'
+	## --no-generator does not do the trick on Debian Jessie.
 	rst2html --stylesheet=examples/demo.css examples/main.rst | grep --invert-match --fixed-strings '<meta name="generator"' > examples/main.html
 	rst2html --stylesheet=examples/demo.css tests/patternsTest.rst > tests/patternsTest.html
 

docs/fold-markers.rst

@@ -7,7 +7,7 @@ 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:
+So to use folds in your files, you basally have three options:
 
 #. Use reStructuredText comments for fold markers. Example:
 
@@ -66,7 +66,9 @@ So to use folds in your files, you basally have two options:
       # -------------------
       #
 
-Both variants have their pros and cons and both are supported by `yaml2rst`, so
+#. Extend your editor by writing a function to recognize the fold levels automatically.
+
+Three variants have their pros and cons and both are supported by `yaml2rst`, so
 you can choose.
 
 Advantages of using reStructuredText comments for fold markers:
@@ -80,12 +82,27 @@ Advantages of using reStructuredText comments for fold markers:
 
 Advantages of appending your fold markers directly after reStructuredText headings:
 
+* The whole section line can be used as folding comment in other files as well.
+  In the context of Ansible, you can copy a section from the
+  `defaults/main.yml` file and use it as is for the implementation in a `tasks`
+  file.
+
 * 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.
+  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.
+
+Advantages for doing folds with a custom function:
+
+* No changes to the files needed
+* People who don’t want folds don’t see any extra wired character sequences in the files.
+
+Disadvantages for doing folds with a custom function:
+
+* Is not as flexible (additional folds can not easily be added)
+* Editor dependent (fold markers are expected to be a somewhat common features of editors)
 
 Which fold marker to use
 ------------------------
@@ -99,3 +116,90 @@ Now a short hash up regarding which fold markers to use.
 * ``(((`` is more likely to appear in Ansible/YAML/Jinja.
 
 * ``[[[`` is not expected to appear in Ansible/YAML/Jinja. Current recommendation.
+
+Folding format of the DebOps project
+------------------------------------
+
+Consider this example which is a result of the thoughts from above:
+
+.. Redundant block of information also included in:
+   * ../examples/fold-markers-debops.yml
+   (Reason: https://github.com/github/markup/issues/172)
+
+.. code:: yaml
+
+   ---
+   # .. vim: foldmarker=[[[,]]]:foldmethod=marker
+
+   # debops.example default variables [[[
+   # ====================================
+
+   # .. contents:: Sections
+   #    :local:
+
+
+   # Main configuration [[[
+   # ----------------------
+
+   # .. envvar:: example__enabled [[[
+   #
+   # Some text describing this boolean.
+   example__enabled: True
+
+                                                                      # ]]]
+   # .. envvar:: example__packages [[[
+   #
+   # List of additional APT packages which will be installed by the role.
+   example__packages: []
+                                                                      # ]]]
+                                                                      # ]]]
+   # Something [[[
+   # -------------
+
+   # .. envvar:: example__something [[[
+   #
+   # Some text describing this list.
+   example__periodic: []
+
+                                                                      # ]]]
+                                                                      # ]]]
+                                                                      # ]]]
+
+Features:
+
+* Closing markers for ``envvar`` folds are indented so that they match a 72
+  character long line. This makes it easier to see where a ``envvar`` block
+  ends and the next once begins when you look on the left part of the line.
+
+* Does not explicitly set the fold marker level to allow the file to be
+  combined into one larger file if needed.
+
+Possible problems:
+
+* When using a YAML block literals, the indented ``# ]]]`` will be part of the
+  variable. Example:
+
+  .. code:: yaml
+
+     # .. envvar:: example__packages [[[
+     #
+     # List of additional APT packages which will be installed by the role.
+     example__text: |
+       Example text
+                                                                      # ]]]
+
+  To avoid this, use:
+
+  .. code:: yaml
+
+     # .. envvar:: example__packages [[[
+     #
+     # List of additional APT packages which will be installed by the role.
+     example__text: |
+       Example text
+     # ]]]
+
+  In this one case.
+
+* Editors with auto indention might start at the ``# ]]]`` indention level when
+  adding a newline after it.

examples/fold-markers-debops.yml

@@ -0,0 +1,36 @@
+---
+# .. File content redundant to ../docs/fold-markers.rst (inlined)
+# .. vim: foldmarker=[[[,]]]:foldmethod=marker
+
+# debops.example default variables [[[
+# ====================================
+
+# .. contents:: Sections
+#    :local:
+
+
+# Main configuration [[[
+# ----------------------
+
+# .. note:: example__enabled [[[
+#
+# Some text describing this boolean.
+example__enabled: True
+
+                                                                  # ]]]
+# .. envvar:: example__packages [[[
+#
+# List of additional APT packages which will be installed by the role.
+example__packages: []
+                                                                  # ]]]
+                                                                  # ]]]
+# Something [[[
+# -------------
+
+# .. envvar:: example__something [[[
+#
+# Some text describing this list.
+example__periodic: []
+                                                                  # ]]]
+                                                                  # ]]]
+                                                                  # ]]]

examples/main.html

@@ -3,7 +3,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<title>collectd</title>
+<title></title>
 <style type="text/css">
 
 /* Layout shamelessly ripped out from https://docs.python.org/2/ */
@@ -51,9 +51,60 @@
 </style>
 </head>
 <body>
-<div class="document" id="collectd">
-<h1 class="title">collectd</h1>
+<div class="document">
 
+
+<!-- File content redundant to ../docs/fold-markers.rst (inlined) -->
+<!-- vim: foldmarker=[[[,]]]:foldmethod=marker -->
+<div class="section" id="debops-example-default-variables">
+<h1>debops.example default variables</h1>
+<div class="contents local topic" id="sections">
+<p class="topic-title first">Sections</p>
+<ul class="simple">
+<li><a class="reference internal" href="#main-configuration" id="id1">Main configuration</a></li>
+<li><a class="reference internal" href="#something" id="id2">Something</a></li>
+</ul>
+</div>
+<div class="section" id="main-configuration">
+<h2><a class="toc-backref" href="#id1">Main configuration</a></h2>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">example__enabled</p>
+</div>
+<p>Some text describing this boolean.</p>
+<pre class="literal-block">
+example__enabled: True
+
+                                                                  # ]]]
+</pre>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">example__packages</p>
+</div>
+<p>List of additional APT packages which will be installed by the role.</p>
+<pre class="literal-block">
+example__packages: []
+                                                                  # ]]]
+                                                                  # ]]]
+</pre>
+</div>
+<div class="section" id="something">
+<h2><a class="toc-backref" href="#id2">Something</a></h2>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">example__something</p>
+</div>
+<p>Some text describing this list.</p>
+<pre class="literal-block">
+example__periodic: []
+                                                                  # ]]]
+                                                                  # ]]]
+                                                                  # ]]]
+</pre>
+</div>
+</div>
+<div class="section" id="collectd">
+<h1>collectd</h1>
 <p>Set this to <tt class="docutils literal">true</tt> to install <cite>collectd</cite>:</p>
 <pre class="literal-block">
 collectd: false
@@ -112,7 +163,7 @@ <h1 class="title">collectd</h1>
   Disk &quot;/hd[0-9]+/&quot;
 </pre>
 <div class="section" id="default-configuration">
-<h1>Default Configuration</h1>
+<h2>Default Configuration</h2>
 <p>The default configuration for each plugin is as follows</p>
 <pre class="literal-block">
 collectd_plugins_default_config:
@@ -140,7 +191,7 @@ <h1>Default Configuration</h1>
 </pre>
 </div>
 <div class="section" id="indention-of-literal-blocks-behind-lists">
-<h1>Indention of Literal Blocks behind Lists</h1>
+<h2>Indention of Literal Blocks behind Lists</h2>
 <p>Code will properly be indented after lists:</p>
 <ul>
 <li><p class="first">list-entry 1</p>
@@ -165,7 +216,7 @@ <h1>Indention of Literal Blocks behind Lists</h1>
 </pre>
 </div>
 <div class="section" id="formatting-as-definition-lists">
-<h1>Formatting as Definition Lists</h1>
+<h2>Formatting as Definition Lists</h2>
 <dl class="docutils">
 <dt>postfix_relayhost</dt>
 <dd><p class="first">Address of mail host this host should relay all mail to instead of
@@ -186,5 +237,6 @@ <h1>Formatting as Definition Lists</h1>
 End: -->
 </div>
 </div>
+</div>
 </body>
 </html>

examples/main.rst

@@ -1,3 +1,47 @@
+.. File content redundant to ../docs/fold-markers.rst (inlined)
+.. vim: foldmarker=[[[,]]]:foldmethod=marker
+
+debops.example default variables
+====================================
+
+.. contents:: Sections
+   :local:
+
+
+Main configuration
+----------------------
+
+.. note:: example__enabled
+
+Some text describing this boolean.
+::
+
+  example__enabled: True
+
+                                                                    # ]]]
+
+.. note:: example__packages
+
+List of additional APT packages which will be installed by the role.
+::
+
+  example__packages: []
+                                                                    # ]]]
+                                                                    # ]]]
+
+Something
+-------------
+
+.. note:: example__something
+
+Some text describing this list.
+::
+
+  example__periodic: []
+                                                                    # ]]]
+                                                                    # ]]]
+                                                                    # ]]]
+
 collectd
 ================