Improved the tutorial

Author: evildmp

CHANGES.rst

@@ -84,6 +84,11 @@ Fixed:
   and importlib_metadata 3.6)
 * Handle deprecation of distutils in Python 3.10 (use the packaging package)
 
+Documentation:
+
+* Started a new Tutorial section.
+* Rewrote the first four paragraphs of the home page, to say: what rinohtype
+  is, what it does, what problem it solves and whose needs it meets.
 
 Release 0.5.3 (2021-06-16)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/tutorial/configuring-stylesheet.rst

@@ -0,0 +1,43 @@
+Working with the stylesheet
+===========================
+
+To recap what we've built so far:
+
+* a Sphinx project containing some content across multiple sections
+* a PDF version of the output, using rinohtype's Sphinx builder, alongside
+  Sphinx's built-in HTML rendering
+* a local template configuration file, ``my-article.rtt``, that is invoked in
+  ``conf.py``, and tells rinotype to:
+
+  * use the built-in ``article`` template
+  * apply a stylesheet, ``allaboutme.rts``, that extends the built-in
+    ``sphinx`` stylesheet
+
+----
+
+You'll notice that each chapter of your document (*Plans*, *Skills*) starts on
+an odd-numbered page. If necessary, rinohtype will add a page break (a blank
+page, in effect) before each new chapter in order to force this.
+
+In the :ref:`Sphinx style sheet` you'll find::
+
+    [chapter]
+    page_break=RIGHT
+
+Just as``emphasis`` and ``strong`` are examples of *elements* that it can
+target, so is a ``chapter``. This style rule ensures that each ``chapter``
+starts on a right-hand page.
+
+Override this behaviour by adding::
+
+    [chapter]
+    page_break=LEFT
+
+to your ``allaboutme.rts`` file, and rebuild. You'll now find that every
+chapter starts on an even-numbered page instead.
+
+But in a document this length it seems unnecessary to insert blank pages, so
+change it to ``ANY`` - and now new chapters will start on a new page, on
+either the left or right.
+
+..  note:: Values in rinohtype stylesheets are case-insensitive.

doc/tutorial/content.rst

@@ -11,6 +11,10 @@ entire contents of the file with the following (edit the text to your taste)::
 
     Write a few paragraphs introducing yourself.
 
+
+    Basic formatting examples
+    -------------------------
+
     Basic formatting in reStructuredText includes:
 
     * *emphasis*
@@ -20,8 +24,39 @@ entire contents of the file with the following (edit the text to your taste)::
     Good things to include in your introduction would be a note about what you
     do and where you live.
 
+
+    Some examples of Sphinx elements
+    --------------------------------
+
+    ..  epigraph::
+
+        I'd like to be remembered by my friends and enemies as honest and
+        stylish but slightly sinister. But mostly I'd just like to be
+        remembered.
+
+        -- Me
+
+
+    ..  note:: Take note!
+
+        Include a ``note`` element, like this one, in order to demonstrate
+        how this is handled.
+
+    ..  admonition:: An admonition
+
+        An ``admonition`` is a generic kind of note, amongst several other
+        kinds that Sphinx has to offer.
+
+    ..  toctree::
+        :hidden:
+
+        plans
+        skills
+
+
 Add a new file, ``plans.rst``, containing::
 
+
     My plans
     ========
 
@@ -32,11 +67,83 @@ Add a new file, ``plans.rst``, containing::
 
     Perhaps you have some things that you intend to do in the near future.
 
+    For example, to write some Python code::
+
+        def plot_file(self, filename="", wait=None, resolution=None, bounds=None):
+            """Plots and image encoded as JSON lines in ``filename``. Passes the
+            lines in the supplied JSON file to ``plot_lines()``.
+            """
+
+            bounds = bounds or self.bounds
+
+            with open(filename, "r") as line_file:
+                lines = json.load(line_file)
+
+            self.plot_lines(
+                lines=lines,
+                wait=wait,
+                resolution=resolution,
+                bounds=bounds,
+                flip=True
+            )
+
+    And to quote  a great mind:
+
+        A good will is not good because of what it effects or accomplishes,
+        because of its fitness to attain some proposed end, but only because of
+        its volition, that is, it is good in itself and, regarded for itself,
+        is to be valued incomparably higher than all that could merely be
+        brought about by it in favor of some inclination and indeed, if you
+        will, of the sum of all inclinations.
+
     Long-term plans
     ---------------
 
     And perhaps you have some that will come later on.
 
+    Include an image. If you want a suitable image file, use `Dürer's
+    rhinoceros from Wikipedia
+    <https://en.wikipedia.org/wiki/Dürer's_Rhinoceros#/media/File:The_Rhinocero
+    s_(N GA_1964.8.697)_enhanced.png>`_. Rename it to ``rhino.png`` and place
+    it in the root of your Sphinx project.
+
+    ..  figure:: /rhino.png
+        :figclass: wider
+        :alt:
+
+        Not to be mistaken with rinoh: a rhino.
+
+And another, ``skills.rst``::
+
+    Skills
+    ======
+
+    I enjoy learing new skills.
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus
+    fringilla quis metus id porta. Nullam nibh ligula, mattis at molestie non,
+    interdum eu massa. Curabitur id sapien ut purus interdum lacinia.
+
+    Sed congue ligula sit amet porta pulvinar. Etiam magna risus, porttitor
+    viverra accumsan vel, rutrum quis eros. Curabitur at nibh lacus. Fusce ex
+    massa, pellentesque sed est eu, lacinia sodales nibh. Curabitur volutpat
+    justo a tortor bibendum, sed rutrum purus vestibulum.
+
+    Aliquam aliquet neque id erat cursus, vestibulum condimentum erat
+    convallis. In tristique, quam lacinia semper pretium, ante arcu blandit
+    turpis, non mollis sem magna ac risus.
+
+    Suspendisse pharetra tellus libero, ac aliquet est mattis non. Nunc
+    pretium scelerisque erat sit amet rutrum. Aliquam sit amet ornare mi.
+
+    Morbi lacus purus, elementum et leo nec, dictum dictum nulla. Sed
+    fringilla at elit venenatis molestie. Cras rhoncus enim sed interdum
+    sodales. Proin at sodales quam. Duis auctor libero mattis metus venenatis
+    pretium. Etiam bibendum bibendum nisi, quis vulputate nisi commodo ut.
+
+    Duis semper metus id quam venenatis euismod.
+
+
 The last thing to do is to add a table of contents to the ``index.rst`` file,
 so it knows how to organise the content you have created. At the end of the
 file, add::
@@ -45,11 +152,9 @@ file, add::
         :hidden:
 
         plans
+        skills
 
-You can add additional pages if you wish. For example, if you added
-``my-family.rst``, you would need to add ``my-family`` below ``plans`` in the
-``toctree`` (or indeed above it, if you wanted those sections in a different
-order).
+Add additional pages if you wish.
 
 This isn't the place for a primer on Sphinx and rST, so you should look for
 other resources if you need guidance on more ambitious formatting at this

doc/tutorial/custom-template.rst

@@ -45,9 +45,8 @@ use::
 ``template = article`` refers to rinohtype's built-in ``article`` template (a
 template is defined in Python).
 
- ``stylesheet = allaboutme.rts`` tells
-rinohtype to use a particular stylesheet, which we need to create now as our
-final step::
+``stylesheet = allaboutme.rts`` tells rinohtype to use a particular
+stylesheet, which we need to create now as our final step::
 
     [STYLESHEET]
     name=My custom style sheet
@@ -60,10 +59,10 @@ final step::
     font_color=#0f0
 
 Here we told rinohtype to inherit from the built-in ``sphinx``
-stylesheet, and apply colors to *emphasis* and *strong* elements.
+stylesheet, and apply RGB colours to *emphasis* and *strong* elements.
 
-Rebuild the PDF to check that your changes have taken effect. You should
-notice that the new PDF is more compact than the previous version, with fewer
-blank pages. This is because we're now using rinohtype's ``article`` template,
-rather than the default ``book`` - ``book`` is more suited to much longer
-material, laid out as a traditional book.
+Rebuild the PDF to check that your changes have taken effect. As well as the
+new colours, you should see that the new PDF is more compact than the previous
+version, with fewer blank pages. This is because we're now using rinohtype's
+``article`` template, rather than the default ``book`` - ``book`` is more
+suited to much longer material, laid out as a traditional book.

doc/tutorial/customisation.rst

@@ -1,3 +1,5 @@
+.. _tutorial:
+
 Tutorial
 ========
 
@@ -17,4 +19,4 @@ and introduces you to a concept, tool or process in rinohtype.
     install
     content
     customisation
-    custom-template
+    configuring-stylesheet