Tutorial

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/index.rst

@@ -6,15 +6,29 @@
 rinohtype: The Python Document Processor
 ========================================
 
+rinohtype is a Python library, including a Sphinx builder, for creating
+typeset PDFs from a structured document source. Its focus is on complex
+documents such as technical manuals, but it can be used to create any kind of
+document.
+
+It processes reStructuredText and Markdown source and builds its output using
+Python-based templates and CSS-inspired stylesheets. Through its granular API
+and programmatic approach to document structures it makes possible a
+repeatable, consistent document generation workflow.
+
+rinohtype addresses a need for accessible and extensible methods of PDF
+creation, that include sophisticated control of styling and presentation for
+complex materials, alongside well-established workflows for HTML.
+
+rinohtype is especially useful for maintainers of information in rST and
+Markdown who want to provide PDF verions of their content.
+
+------
+
 .. todolist::
 
 Release v\ |version|. (:ref:`Release History <changelog>`)
 
-rinohtype is a Python library that transforms a structured document into a
-professionally typeset PDF guided by a document template and style sheet. It
-can be used to create any kind of document, but its focus is on complex
-documents such as technical manuals.
-
 Included with rinohtype is the :program:`rinoh` command line tool that renders
 reStructuredText and Markdown (CommonMark) documents. There is also a
 commercial DITA_ frontend, but its development is currently on hold. Please

doc/manual.rst

@@ -1,10 +1,10 @@
-
 .. toctree::
     :caption: User Manual
     :maxdepth: 2
     :hidden:
 
     intro
+    manual/index
     install
     quickstart
     basicstyling

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

@@ -0,0 +1,166 @@
+Creating content
+======================
+
+Now is an appropriate time to add some content to work with.
+
+The first page of the project is the ``index.rst`` file. You can replace the
+entire contents of the file with the following (edit the text to your taste)::
+
+    All about me
+    ============
+
+    Write a few paragraphs introducing yourself.
+
+
+    Basic formatting examples
+    -------------------------
+
+    Basic formatting in reStructuredText includes:
+
+    * *emphasis*
+    * **strong emphasis**
+    * asterisks for list items
+
+    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
+    ========
+
+    Say something about your plans.
+
+    Short-term plans
+    ----------------
+
+    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::
+
+    ..  toctree::
+        :hidden:
+
+        plans
+        skills
+
+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
+stage.
+
+Run ``make html`` and reload the ``index.html`` page to see the new content as
+HTML; run ``make rinoh`` and re-open ``allaboutme.pdf`` to see the new version
+of the PDF (if you're lucky, your PDF viewer will reload the changed file for
+your automatically).

doc/tutorial/customisation.rst

@@ -0,0 +1,68 @@
+Basic customisation
+====================
+
+HTML
+----
+
+The next step is to manage *how* Sphinx builds the project. It's useful to use
+an HTML theme whose output corresponds better to PDF rendering, so switch to
+Furo; in ``conf.py``, edit the ``html_theme`` setting, to::
+
+    html_theme = 'furo'
+
+Rebuild the HTML to see the effect.
+
+
+PDF
+---
+
+The PDF customisation is a little more complex. We need to do three things.
+
+First, apply some rinoh configuration in ``conf.py``::
+
+    rinoh_documents = [
+        {
+            "doc": "index",
+            "target": "allaboutme",
+            "template": "my-article.rtt"
+        }
+    ]
+
+In brief, this means:
+
+* build a document using the ``index`` file as the root
+* name the output ``allaboutme``
+* use the template configuration file in ``my-article.rtt``.
+
+Next, create the ``my-article.rtt`` template configuration file that this will
+use::
+
+    [TEMPLATE_CONFIGURATION]
+    name = My custom configuration
+    template = article
+    stylesheet = allaboutme.rts
+
+``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]
+    name=My custom style sheet
+    base=sphinx
+
+    [emphasis]
+    font_color=#f00
+
+    [strong]
+    font_color=#0f0
+
+Here we told rinohtype to inherit from the built-in ``sphinx``
+stylesheet, and apply RGB colours to *emphasis* and *strong* elements.
+
+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/index.rst

@@ -0,0 +1,22 @@
+.. _tutorial:
+
+Tutorial
+========
+
+This tutorial is intended to provide a practical introduction to using
+rinohtype.
+
+It uses Sphinx to create a multi-page document, that rinohtype renders
+as a PDF, complete with customised templates and styling.
+
+Work through the tutorial step-by-step. Each step builds on the previous one,
+and introduces you to a concept, tool or process in rinohtype.
+
+
+..  toctree::
+    :maxdepth: 1
+
+    install
+    content
+    customisation
+    configuring-stylesheet