update doc

10 files changed, 66 insertions, 87 deletions

diff --git a/_doc/api.ryd b/_doc/api.ryd
index 314bfbd..8bdf9a4 100644
--- a/_doc/api.ryd
+++ b/_doc/api.ryd
@@ -1,5 +1,5 @@
-version: 0.1
-output: rst
+version: 0.2
+text: rst
 fix_inline_single_backquotes: true
 pdf: true
 --- !python-pre |
@@ -47,17 +47,19 @@ Starting with 0.15.0 ``load()`` and ``dump()`` are methods on a
 resp. the data and stream argument. All other parameters are set on the instance
 of ``YAML`` before calling ``load()`` or ``dump()``
 
-Before 0.15.0::
---- !python |
-from pathlib import Path
-from ruamel import yaml
+Before 0.15.0 you could do:
 
-data = yaml.safe_load("abc: 1")
-out = Path('/tmp/out.yaml')
-with out.open('w') as fp:
-    yaml.safe_dump(data, fp, default_flow_style=False)
---- |
-after::
+.. code:: python
+
+    from pathlib import Path
+    from ruamel import yaml
+
+    data = yaml.safe_load("abc: 1")
+    out = Path('/tmp/out.yaml')
+    with out.open('w') as fp:
+        yaml.safe_dump(data, fp, default_flow_style=False)
+
+after:
 --- !python |
 from pathlib import Path
 from ruamel.yaml import YAML
@@ -111,7 +113,7 @@ PyYAML never enforced this although the YAML 1.1 specification already
 required this.
 
 In the new API (starting 0.15.1) duplicate keys in mappings are no longer allowed by
-default. To allow duplicate keys in mappings::
+default. To allow duplicate keys in mappings:
 
 --- !python |
 yaml = ruamel.yaml.YAML()
@@ -213,18 +215,17 @@ for reading resp.  writing.
 
 Loading and dumping using the ``SafeLoader``::
 
---- !python |
-if ruamel.yaml.version_info < (0, 15):
-    data = yaml.safe_load(istream)
-    yaml.safe_dump(data, ostream)
-else:
-    yml = ruamel.yaml.YAML(typ='safe', pure=True)  # 'safe' load and dump
-    data = yml.load(istream)
-    yml.dump(data, ostream)
---- |
+    if ruamel.yaml.version_info < (0, 15):
+        data = yaml.safe_load(istream)
+        yaml.safe_dump(data, ostream)
+    else:
+        yml = ruamel.yaml.YAML(typ='safe', pure=True)  # 'safe' load and dump
+        data = yml.load(istream)
+        yml.dump(data, ostream)
+
 Loading with the ``CSafeLoader``, dumping with
 ``RoundTripLoader``. You need two ``YAML`` instances, but each of them
-can be re-used::
+can be re-used:
 --- !python |
 if ruamel.yaml.version_info < (0, 15):
     data = yaml.load(istream, Loader=yaml.CSafeLoader)
diff --git a/_doc/basicuse.ryd b/_doc/basicuse.ryd
index ca5139b..35e7c38 100644
--- a/_doc/basicuse.ryd
+++ b/_doc/basicuse.ryd
@@ -1,5 +1,5 @@
-version: 0.1
-output: rst
+version: 0.2
+text: rst
 fix_inline_single_backquotes: true
 pdf: true
 --- !python-pre |
@@ -15,7 +15,7 @@ data = dict(a=1)
 Basic Usage
 ***********
 
-You load a YAML document using::
+You load a YAML document using:
 --- !python |
 from ruamel.yaml import YAML
 
@@ -43,7 +43,7 @@ in this ``s`` can be a file pointer (i.e. an object that has the
 your output, just stream to ``sys.stdout``.
 
 If you need to transform a string representation of the output provide
-a function that takes a string as input and returns one::
+a function that takes a string as input and returns one:
 
 --- !python |
 def tr(s):
@@ -56,7 +56,7 @@ More examples
 =============
 
 Using the C based SafeLoader (at this time is inherited from
-libyaml/PyYAML and e.g. loads ``0o52`` as well as ``052`` load as integer ``42``)::
+libyaml/PyYAML and e.g. loads ``0o52`` as well as ``052`` load as integer ``42``):
 
 --- !python |
    from ruamel.yaml import YAML
@@ -65,7 +65,7 @@ libyaml/PyYAML and e.g. loads ``0o52`` as well as ``052`` load as integer ``42``
    yaml.load("""a:\n  b: 2\n  c: 3\n""")
 
 --- |
-Using the Python based SafeLoader (YAML 1.2 support, ``052`` loads as ``52``)::
+Using the Python based SafeLoader (YAML 1.2 support, ``052`` loads as ``52``):
 --- !python |
    from ruamel.yaml import YAML
 
diff --git a/_doc/contributing.ryd b/_doc/contributing.ryd
index a2ad397..96bce11 100644
--- a/_doc/contributing.ryd
+++ b/_doc/contributing.ryd
@@ -1,5 +1,5 @@
-version: 0.1
-output: rst
+version: 0.2
+text: rst
 fix_inline_single_backquotes: true
 pdf: true
 --- |
diff --git a/_doc/detail.ryd b/_doc/detail.ryd
index 00d0b8c..b25c939 100644
--- a/_doc/detail.ryd
+++ b/_doc/detail.ryd
@@ -1,5 +1,5 @@
-version: 0.1
-output: rst
+version: 0.2
+text: rst
 fix_inline_single_backquotes: true
 --- |
 *******
@@ -179,7 +179,7 @@ adding/replacing comments
 
 Starting with version 0.8, you can add/replace comments on block style
 collections (mappings/sequences resuting in Python dict/list). The basic
-for for this is::
+for for this is:
 --- !python |
   from __future__ import print_function
 
@@ -205,7 +205,7 @@ for for this is::
   data['abc'].yaml_add_eol_comment('comment 4', 1)  # takes column of comment 1
   data['xyz'].yaml_add_eol_comment('comment 5', 'c')  # takes column of comment 2
   data['xyz'].yaml_add_eol_comment('comment 6', 'e')  # takes column of comment 3
-  data['xyz'].yaml_add_eol_comment('comment 7', 'd', column=20)
+  data['xyz'].yaml_add_eol_comment('comment 7\n\n# that\'s all folks', 'd', column=20)
 
   yaml.dump(data, sys.stdout)
 --- !stdout |
@@ -229,6 +229,10 @@ from the example, the column to choose for a comment is derived
 from the previous, next or preceding comment column (picking the first one
 found).
 
+Make sure that the added comment is correct, in the sense that when it
+contains newlines, the following is either an empty line or a line with
+only spaces, or the first non-space is a `#`.
+
 Config file formats
 +++++++++++++++++++
 
diff --git a/_doc/dumpcls.ryd b/_doc/dumpcls.ryd
index 929d5f5..8e9ac6e 100644
--- a/_doc/dumpcls.ryd
+++ b/_doc/dumpcls.ryd
@@ -1,5 +1,5 @@
-version: 0.1
-output: rst
+version: 0.2
+text: rst
 fix_inline_single_backquotes: true
 pdf: true
 # code_directory: ../_example
@@ -16,7 +16,7 @@ If you have instances of some class(es) that you want to dump or load, it is
 easy to allow the YAML instance to do that explicitly. You can either register the
 class with the ``YAML`` instance or decorate the class.
 
-Registering is done with ``YAML.register_class()``::
+Registering is done with ``YAML.register_class()``:
 
 --- !python |
 
@@ -40,7 +40,7 @@ The tag ``!User`` originates from the name of the class.
 
 You can specify a different tag by adding the attribute ``yaml_tag``, and
 explicitly specify dump and/or load *classmethods* which have to be called
-``to_yaml`` resp. ``from_yaml``::
+``to_yaml`` resp. ``from_yaml``:
 
 --- !python |
 import sys
@@ -73,7 +73,7 @@ which gives as output::
 --- |
 
 When using the decorator, which takes the ``YAML()`` instance as a parameter,
-the ``yaml = YAML()`` line needs to be moved up in the file::
+the ``yaml = YAML()`` line needs to be moved up in the file:
 
 --- !python |
 import sys
diff --git a/_doc/example.ryd b/_doc/example.ryd
index 44a3f2c..c38ead0 100644
--- a/_doc/example.ryd
+++ b/_doc/example.ryd
@@ -1,5 +1,5 @@
-version: 0.1
-output: rst
+version: 0.2
+text: rst
 fix_inline_single_backquotes: true
 pdf: true
 --- |
@@ -8,7 +8,7 @@ Examples
 ********
 
 Basic round trip of parsing YAML to Python objects, modifying
-and generating YAML::
+and generating YAML:
 --- !python |
   import sys
   from ruamel.yaml import YAML
@@ -30,37 +30,11 @@ and generating YAML::
 --- !stdout |
 Resulting in::
 --- |
-with the old API::
---- !python |
-  from __future__ import print_function
-
-  import sys
-  import ruamel.yaml
-
-  inp = """\
-  # example
-  name:
-    # details
-    family: Smith   # very common
-    given: Alice    # one of the siblings
-  """
-
-  code = ruamel.yaml.load(inp, ruamel.yaml.RoundTripLoader)
-  code['name']['given'] = 'Bob'
-
-  ruamel.yaml.dump(code, sys.stdout, Dumper=ruamel.yaml.RoundTripDumper)
-
-  # the last statement can be done less efficient in time and memory with
-  # leaving out the end='' would cause a double newline at the end
-  # print(ruamel.yaml.dump(code, Dumper=ruamel.yaml.RoundTripDumper), end='')
---- !stdout |
-Resulting in ::
---- |
 ----
 
 YAML handcrafted anchors and references as well as key merging
 are preserved. The merged keys can transparently be accessed
-using ``[]`` and ``.get()``::
+using ``[]`` and ``.get()``:
 --- !python |
   from ruamel.yaml import YAML
 
@@ -94,7 +68,7 @@ using ``[]`` and ``.get()``::
 --- |
 
 The ``CommentedMap``, which is the ``dict`` like construct one gets when round-trip loading,
-supports insertion of a key into a particular position, while optionally adding a comment::
+supports insertion of a key into a particular position, while optionally adding a comment:
 --- !python |
   import sys
   from ruamel.yaml import YAML
@@ -125,7 +99,7 @@ both mappings and sequences. For sequences the indent is counted to the
 beginning of the scalar, with the dash taking the first position of the
 indented "space".
 
-You can change this default indentation by e.g. using ``yaml.indent()``::
+You can change this default indentation by e.g. using ``yaml.indent()``:
 
 
 --- !python |
@@ -157,7 +131,7 @@ that the dash of the "parent" sequence is on the same line as the
 first element resp. first key/value pair of the child collection.
 
 If you want either or both of these (sequence within sequence, mapping
-within sequence) to begin on the next line use ``yaml.compact()``::
+within sequence) to begin on the next line use ``yaml.compact()``:
 
 --- !python |
 
@@ -183,7 +157,7 @@ giving::
 ------
 
 The following program uses three dumps on the same data, resulting in a stream with 
-three documents::
+three documents:
 
 --- !python |
 import sys
@@ -259,7 +233,7 @@ sys.stdout)`` and do away with 90% of the cases for returning the string, and
 that all post-processing YAML, before writing to stream, can be handled by using
 the ``transform=`` parameter of dump, being able to handle most of the rest. But
 it is also much easier in the new API to provide that YAML output as a string if
-you really need to have it (or think you do)::
+you really need to have it (or think you do):
 
 --- !python |
 import sys
diff --git a/_doc/index.ryd b/_doc/index.ryd
index 0ed9070..9333020 100644
--- a/_doc/index.ryd
+++ b/_doc/index.ryd
@@ -1,5 +1,5 @@
-version: 0.1
-output: rst
+version: 0.2
+text: rst
 fix_inline_single_backquotes: true
 pdf: false
 --- !comment |
diff --git a/_doc/install.ryd b/_doc/install.ryd
index 1da00b8..2d54849 100644
--- a/_doc/install.ryd
+++ b/_doc/install.ryd
@@ -1,5 +1,5 @@
-version: 0.1
-output: rst
+version: 0.2
+text: rst
 fix_inline_single_backquotes: true
 # pdf: true
 --- |
@@ -50,5 +50,5 @@ For CentOS (7) based systems you should do::
 
    sudo yum install python-devel
 
---- !incraw |
+--- !inc-raw |
 links.rydinc
diff --git a/_doc/overview.ryd b/_doc/overview.ryd
index 38b9b52..43be596 100644
--- a/_doc/overview.ryd
+++ b/_doc/overview.ryd
@@ -1,5 +1,5 @@
-version: 0.1
-output: rst
+version: 0.2
+text: rst
 fix_inline_single_backquotes: true
 --- |
 ********
@@ -47,5 +47,5 @@ Many of the bugs filed against PyYAML, but that were never
 acted upon, have been fixed in ``ruamel.yaml``
 
 
---- !incraw |
+--- !inc-raw |
 links.rydinc
diff --git a/_doc/pyyaml.ryd b/_doc/pyyaml.ryd
index a9f7dd0..56ee391 100644
--- a/_doc/pyyaml.ryd
+++ b/_doc/pyyaml.ryd
@@ -1,5 +1,5 @@
-version: 0.1
-output: rst
+version: 0.2
+text: rst
 fix_inline_single_backquotes: true
 pdf: true
 --- |
@@ -80,5 +80,5 @@ API
 Starting with 0.15 the API for using ``ruamel.yaml`` has diverged allowing 
 easier addition of new features.
 
---- !incraw |
-links.rydinc
+--- !inc-raw
+- links.rydinc