From 153b830be04f3ae67da2047abf324f9a088099ce Mon Sep 17 00:00:00 2001 From: Robin Schneider Date: Tue, 12 Jul 2016 19:03:47 +0200 Subject: [PATCH] Fold format: Documented decision process and outcome for the DebOps project. Related to: https://github.com/debops/docs/issues/156 --- Makefile | 3 +- docs/fold-markers.rst | 116 +++++++++++++++++++++++++++++-- examples/fold-markers-debops.yml | 36 ++++++++++ examples/main.html | 64 +++++++++++++++-- examples/main.rst | 44 ++++++++++++ 5 files changed, 250 insertions(+), 13 deletions(-) create mode 100644 examples/fold-markers-debops.yml diff --git a/Makefile b/Makefile index f298351..1093888 100644 --- a/Makefile +++ b/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 ' examples/main.html rst2html --stylesheet=examples/demo.css tests/patternsTest.rst > tests/patternsTest.html diff --git a/docs/fold-markers.rst b/docs/fold-markers.rst index f88e434..534dea4 100644 --- a/docs/fold-markers.rst +++ b/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. diff --git a/examples/fold-markers-debops.yml b/examples/fold-markers-debops.yml new file mode 100644 index 0000000..08e6882 --- /dev/null +++ b/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: [] + # ]]] + # ]]] + # ]]] diff --git a/examples/main.html b/examples/main.html index 9363a0d..08fbea1 100644 --- a/examples/main.html +++ b/examples/main.html @@ -3,7 +3,7 @@ -collectd + -
-

collectd

+
+ + + +
+

debops.example default variables

+
+

Sections

+ +
+
+

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

Set this to true to install collectd:

 collectd: false
@@ -112,7 +163,7 @@ 
collectd

   Disk "/hd[0-9]+/"
-

Default Configuration

+

Default Configuration

The default configuration for each plugin is as follows

 collectd_plugins_default_config:
@@ -140,7 +191,7 @@ 
Default Configuration
-

Indention of Literal Blocks behind Lists

+

Indention of Literal Blocks behind Lists

Code will properly be indented after lists:

  • list-entry 1

    @@ -165,7 +216,7 @@

    Indention of Literal Blocks behind Lists

-

Formatting as Definition Lists

+

Formatting as Definition Lists

postfix_relayhost

Address of mail host this host should relay all mail to instead of @@ -186,5 +237,6 @@

Formatting as Definition Lists

End: -->
+
diff --git a/examples/main.rst b/examples/main.rst index 3d5a309..c778ae7 100644 --- a/examples/main.rst +++ b/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 ================