doc generation test 1

8 files changed, 72 insertions, 10 deletions

diff --git a/.readthedocs.yml b/.readthedocs.yml
index 010fb06..914f036 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -1,2 +1,4 @@
 python:
+  version: 3
   pip_install: true
+  extra_requirements: [docs]
diff --git a/__init__.py b/__init__.py
index fc6ce3f..580844c 100644
--- a/__init__.py
+++ b/__init__.py
@@ -18,6 +18,7 @@ _package_data = dict(
         ':platform_python_implementation=="CPython" and python_version<="2.7"':
         ['ruamel.ordereddict'],
         'jinja2': ['ruamel.yaml.jinja2>=0.2'],
+        'docs': ['ryd'],
     },
     ext_modules=[dict(
         name='_ruamel_yaml',
diff --git a/_doc/conf.py b/_doc/conf.py
index 94f85e5..9ec0f33 100644
--- a/_doc/conf.py
+++ b/_doc/conf.py
@@ -61,6 +61,7 @@ try:
     version = release = __version__
 except:
     version = release = 'dev'
+print('ruamel.yaml version', version)
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/_doc/example.rst b/_doc/example.rst
index 418fe44..a2cdf78 100644
--- a/_doc/example.rst
+++ b/_doc/example.rst
@@ -130,9 +130,10 @@ posted by *demux* on StackOverflow.
 
 ----
 
-By default `ruamel.yaml` indents with two positions in block style, for
-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".
+By default ``ruamel.yaml`` indents with two positions in block style, for
+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".
 
 The following program with three dumps::
 
diff --git a/_doc/example.ryd b/_doc/example.ryd
index b6b4147..2907048 100644
--- a/_doc/example.ryd
+++ b/_doc/example.ryd
@@ -2,6 +2,7 @@
 version: 0.1
 output: rst
 fix_inline_single_backquotes: true
+pdf: true
 --- |
 ********
 Examples
@@ -120,9 +121,10 @@ posted by *demux* on StackOverflow.
 
 ----
 
-By default `ruamel.yaml` indents with two positions in block style, for
-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".
+By default ``ruamel.yaml`` indents with two positions in block style, for
+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".
 
 The following program with three dumps::
 --- !python |
diff --git a/_doc/install.rst b/_doc/install.rst
index 78f53d9..3ee8ff9 100644
--- a/_doc/install.rst
+++ b/_doc/install.rst
@@ -9,7 +9,7 @@ not with 3.4.4. It is probably best to do::
 
     pip install -U pip setuptools wheel
 
-in your environment (`virtualenv`, (Docker) container, etc) before
+in your environment (``virtualenv``, (Docker) container, etc) before
 installing ``ruamel.yaml``.
 
 ``ruamel.yaml`` itself should be installed from PyPI_ using::
@@ -44,3 +44,5 @@ you can leave out ``python3-dev`` if you don't use python3
 For CentOS (7) based systems you should do::
 
    sudo yum install python-devel
+
+.. include:: links.rst
diff --git a/_doc/install.ryd b/_doc/install.ryd
new file mode 100644
index 0000000..4020772
--- /dev/null
+++ b/_doc/install.ryd
@@ -0,0 +1,54 @@
+---
+version: 0.1
+output: rst
+fix_inline_single_backquotes: true
+# pdf: true
+--- |
+**********
+Installing
+**********
+
+Make sure you have a recent version of ``pip`` and ``setuptools``
+installed. The later needs environment marker support
+(``setuptools>=20.6.8``) and that is e.g.  bundled with Python 3.4.6 but
+not with 3.4.4. It is probably best to do::
+
+    pip install -U pip setuptools wheel
+
+in your environment (``virtualenv``, (Docker) container, etc) before
+installing ``ruamel.yaml``.
+
+``ruamel.yaml`` itself should be installed from PyPI_ using::
+
+    pip install ruamel.yaml
+
+If you want to process jinja2/YAML templates (which are not valid YAML
+with the default jinja2 markers), do ``pip install
+ruamel.yaml[jinja2]`` (you might need to quote the last argument
+because of the ``[]``)
+
+
+There also is a commandline utility ``yaml`` available after installing::
+
+   pip install ruamel.yaml.cmd
+
+that allows for round-trip testing/re-indenting and conversion of YAML
+files (JSON,INI,HTML tables)
+
+Optional requirements
++++++++++++++++++++++
+
+If you have the the header files for your Python executables installed
+then you can use the (non-roundtrip), but faster, C loader and emitter.
+
+On Debian systems you should use::
+
+    sudo apt-get install python3-dev
+
+you can leave out ``python3-dev`` if you don't use python3
+
+For CentOS (7) based systems you should do::
+
+   sudo yum install python-devel
+
+.. include:: links.rst
diff --git a/_doc/links.rst b/_doc/links.rst
index c3dbb1b..7d38c7f 100644
--- a/_doc/links.rst
+++ b/_doc/links.rst
@@ -1,7 +1,6 @@
 .. _tox: https://pypi.python.org/pypi/tox
-.. _py.test: http://pytest.org/latest/ 
+.. _py.test: http://pytest.org/latest/
 .. _YAML 1.1: http://www.yaml.org/spec/1.1/spec.html
 .. _YAML 1.2: http://www.yaml.org/spec/1.2/spec.html
-.. _PyPI: https: https://pypi.python.org/pypi
+.. _PyPI: https://pypi.python.org/pypi
 .. _ruamel.yaml: https://pypi.python.org/pypi/ruamel.yaml
-