removed _example, added contribution.ryd

5 files changed, 124 insertions, 130 deletions

diff --git a/_doc/conf.py b/_doc/conf.py
index f194404..1ded3e1 100644
--- a/_doc/conf.py
+++ b/_doc/conf.py
@@ -141,7 +141,7 @@ html_theme = 'default'
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-html_title = "python YAML package documentation"
+html_title = "Python YAML package documentation"
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 # html_short_title = None
@@ -243,7 +243,7 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'yaml.tex', u'yaml Documentation',
+    (master_doc, 'yaml.tex', u'Python YAML package documentation',
      u'Anthon van der Neut', 'manual'),
 ]
 
diff --git a/_doc/contributing.ryd b/_doc/contributing.ryd
new file mode 100644
index 0000000..3b093d1
--- /dev/null
+++ b/_doc/contributing.ryd
@@ -0,0 +1,122 @@
+---
+version: 0.1
+output: rst
+fix_inline_single_backquotes: true
+pdf: true
+--- |
+************
+Contributing
+************
+
+Any contribution to ``ruamel.yaml`` is welcome, be it in the form of an
+email, a question on stackoverflow (I'll get notified of that when you tag it
+with ``ruamel.yaml``), an issue or pull-request (PR) on bitbucket.
+
+Contributing via stackoverflow is, for most, easiest to make. When I answer your
+question there and the answer warrants an extension to the documentation or
+code, I will include it in a documnetation update and/or future (normally the
+next) release of ``ruamel.yaml``.
+
+Please don't post support questions as an issue on Bitbucket.
+
+Documentation
+=============
+
+The documentation for ``ruamel.yaml`` is in YAML, more specifically in `ryd
+<https://pypi.python.org/pypi/ryd>`_ ( /rɑɪt/, pronounced like the verb “write”
+). This is reStructuredText mixed with Python, each in separate YAML documents
+within a single file. If you know a bit of YAML, Python and reStructuredText it
+will be clear how that works.
+
+If you want to contribute to the documentation, you can sent me a clear
+description of the needed changes, e.g. as a unified diff. If the changes
+encompass multiple documents in a ``.ryd`` file, it is best to install ``ryd``
+(use a virtualenv!), clone the ``ruamel.yaml`` repository on Bitbucket, edit
+documentation, run ``ryd``::
+
+      ryd --pdf '**/*.ryd'
+
+(quoting might not be necessary depending on your shell), and once the PDF(s)
+look acceptable, submit a pull-request.
+
+``ryd`` will check your file for single backquotes (my most common mistake going
+back and forth between reStructuredText and other mark up).
+
+If you contribute example programs, note that ``ryd`` will automatically run you
+program (so it should be correct) and can include the output of the program in
+the resulting ``.rst`` (and PDF) file.
+
+Code
+====
+
+Code changes are welcome as well, but anything beyond a minor change should be
+tested (``tox``/``pytest``), checked for typing conformance (``mypy``) and pass
+pep8 conformance (``flake8``).
+
+In my experience it is best to use two ``virtualenv`` environments, one with the
+latest Python from the 2.7 series, the other with 3.5 or 3.6. In the
+site-packages directory of each virtualenv make a soft link to the ruamel
+directory of your (cloned and checked out) copy of the repository. Do not under
+any circumstances run ``pip install -e .`` or ``python setup.py -e .`` it will
+not work (at least not until these commands are fixed to support packages with
+namespaces).
+
+You can install ``tox``, ``pytest``, ``mypy`` and ``flake8`` in the Python3
+``virtualenv``, or in ``virtualenv``s of their own. If all of these commands
+pass without warning/error, you can create your pull-request.
+
+Flake
++++++
+
+My ``~/.config/flake8`` file::
+
+  [flake8]
+  show-source = True
+  max-line-length = 95
+  ignore = F405
+
+The suppress of F405 is necessary to allow ``from xxx import *``, which I have
+not removed in all places (yet).
+
+First make sure your checked out source passes ``flake8`` without test (it should).
+Then make your changes pass without any warnings/errors.
+
+Tox/pytest
+++++++++++
+
+Wether you add something or fix some bug with your code changes, first add one
+or more tests that fail in the unmodified source when running ``tox``. Once that
+is in place add your code, which should have as a result that your added test(s)
+no longer fail, and neither should any other existing tests.
+
+Typing/mypy
++++++++++++
+
+If you add methods or functions to ``ruamel.yaml``, you will need to add Python
+2.7 compatible typing information in order for ``mypy`` to pass without error.
+
+I run ``mypy`` from the directory where the (link to) ruamel directory is
+using::
+
+    mypy --py2 --strict --follow-imports silent ruamel/yaml/*.py
+
+This should give no errors or warnings
+
+
+Generated files
+===============
+
+I use a minimal environment when developing, void of most artifacts needed for
+packaging, testing etc. These artifact files are *generated*, just before committing to
+Bitbucket and pushing to PyPI, with nuances coming from the ``_package_data``
+information in ``__init__.py``. Including changes in these files will
+automatically be reverted, even assuming your PR is accepted as is.
+
+Consider the following files **read-only** (if you think changes need to made these,
+contact me)::
+
+   setup.py
+   tox.ini
+   LICENSE
+   _ryd/conf.py
+   -ryd/Makefile
diff --git a/_example/map_insert.py b/_example/map_insert.py
deleted file mode 100644
index ab3486a..0000000
--- a/_example/map_insert.py
+++ /dev/null
@@ -1,13 +0,0 @@
-import sys
-from ruamel.yaml import YAML
-
-yaml_str = """\
-first_name: Art
-occupation: Architect  # This is an occupation comment
-about: Art Vandelay is a fictional character that George invents...
-"""
-
-yaml = YAML()
-data = yaml.load(yaml_str)
-data.insert(1, 'last name', 'Vandelay', comment="new key")
-yaml.dump(data, sys.stdout)
diff --git a/_example/so_10241882.py b/_example/so_10241882.py
deleted file mode 100644
index 0dbcb0c..0000000
--- a/_example/so_10241882.py
+++ /dev/null
@@ -1,63 +0,0 @@
-from __future__ import print_function
-
-import ruamel.yaml
-
-inp = """\
-features:
-  show: true
-  items:
-    - widget: full_width.html  # full width 1
-      title: Some Title
-      description: >
-          Foobar.
-      vimeo_id: 20913
-      zoom_image: some_url.png
-    - widget: 3x_container.html
-      items:
-          - widget: 3x.html
-            title: Some Widget Title
-            image: 'foobar.png'
-            description: >
-                Some Description.
-          - widget: 3x.html
-            title: Some new title here
-            image: ajax_uploads/png1_2.png
-            description: >
-                Some Description.
-"""
-
-code = ruamel.yaml.load(inp, ruamel.yaml.RoundTripLoader)
-
-res = ruamel.yaml.dump(code, Dumper=ruamel.yaml.RoundTripDumper)
-print(res, end='')
-code2 = ruamel.yaml.load(res, ruamel.yaml.RoundTripLoader)
-
-res2 = ruamel.yaml.dump(code2, Dumper=ruamel.yaml.RoundTripDumper)
-assert res == res2
-
-inp = """\
-features:
-  show: true
-  items:
-    # full width 1
-    - widget: full_width.html
-      title: Some Title
-      description: >
-        Foobar.
-      vimeo_id: 20913
-      zoom_image: some_url.png
-
-    - widget: 3x_container.html
-      items:
-          - widget: 3x.html
-            title: Some Widget Title
-            image: 'foobar.png'
-            description: >
-                Some Description.
-
-          - widget: 3x.html
-            title: Some new title here
-            image: ajax_uploads/png1_2.png
-            description: >
-                Some Description.
-"""
diff --git a/_example/so_13517753.py b/_example/so_13517753.py
deleted file mode 100644
index af1fc2a..0000000
--- a/_example/so_13517753.py
+++ /dev/null
@@ -1,52 +0,0 @@
-from __future__ import print_function
-
-# import sys
-import ruamel.yaml
-from ruamel.yaml.comments import CommentedMap
-
-# class MyObj():
-#     name = "boby"
-#     age = 34
-#
-# print(ruamel.yaml.dump(MyObj())) # , Dumper=ruamel.yaml.RoundTripDumper), end='')
-#
-# inp = """\
-# boby:       # this is the name
-#    age: 34  # in years
-# """
-#
-# print('====', ruamel.yaml.load(inp))
-#
-#
-# data1 = ruamel.yaml.load(inp, Loader=ruamel.yaml.RoundTripLoader)
-# print('<<<', data1.ca.items)
-# print(ruamel.yaml.dump(data1, Dumper=ruamel.yaml.RoundTripDumper), end='')
-#
-# print('----------------')
-
-
-class MyObj():
-    name = "boby"
-    age = 34
-
-    def convert_to_yaml_struct(self):
-        x = CommentedMap()
-        a = CommentedMap()
-        x[data.name] = a
-        x.yaml_add_eol_comment('this is the name', 'boby', 11)
-        a['age'] = data.age
-        a.yaml_add_eol_comment('in years', 'age', 11)
-        print('>>>', x.ca.items)
-        return x
-
-    @staticmethod
-    def yaml_representer(dumper, data, flow_style=False):
-        assert isinstance(dumper, ruamel.yaml.RoundTripDumper)
-        return dumper.represent_dict(data.convert_to_yaml_struct())
-
-
-ruamel.yaml.RoundTripDumper.add_representer(MyObj, MyObj.yaml_representer)
-
-data = MyObj()
-
-print(ruamel.yaml.dump(data, Dumper=ruamel.yaml.RoundTripDumper), end='')