diff --git a/CHANGES.rst b/CHANGES.rst index 8466e634d..4fc34b501 100644 --- a/CHANGES.rst +++ b/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 (Daniele Procida): + +* 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) ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/index.rst b/doc/index.rst index 3a2efe01e..ca73b0c87 100644 --- a/doc/index.rst +++ b/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 `) -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 diff --git a/doc/manual.rst b/doc/manual.rst index 5ae060399..375d73f47 100644 --- a/doc/manual.rst +++ b/doc/manual.rst @@ -1,10 +1,10 @@ - .. toctree:: :caption: User Manual :maxdepth: 2 :hidden: intro + tutorial/index install quickstart basicstyling diff --git a/doc/tutorial/configuring-stylesheet.rst b/doc/tutorial/configuring-stylesheet.rst new file mode 100644 index 000000000..6e520250e --- /dev/null +++ b/doc/tutorial/configuring-stylesheet.rst @@ -0,0 +1,94 @@ +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 rinohtype to: + + * use the built-in ``article`` template + * apply a stylesheet, ``allaboutme.rts``, that extends the built-in + ``sphinx`` stylesheet + +---- + + +Applying styles to elements +--------------------------- + +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. + + +Using variables in stylesheets +------------------------------ + +In the :ref:`Sphinx style sheet`, you'll see:: + + [VARIABLES] + mono_typeface=TeX Gyre Cursor + serif_typeface=TeX Gyre Pagella + sans_typeface=Tex Gyre Heros + fallback_typeface=DejaVu Serif + thin_black_stroke=0.5pt,#000 + blue=#20435c + + [default:Paragraph] + typeface=$(serif_typeface) + +in which the ``default:Paragraph`` element uses the ``serif_typeface`` variable defined above. + +In your ``allaboutme.rts`` stylesheet, add a ``[VARIABLES]`` section with some definitions +of your own:: + + [VARIABLES] + mono_typeface=IBM Plex Mono + serif_typeface=Joan + sans_typeface=PT Sans + blood-red=#6c1b206 + +These will override the previously-defined fonts. We have also defined a colour, ``blood-red``; +let's use it in the style rules for ``emphasis`` and ``strong`` (notice the syntax, +``$(variable-name)`` for using variables):: + + [emphasis] + font_color=$(blood-red) + + [strong] + font_color=$(blood-red) + +``make rinoh`` again. If rinohtype cannot find the font files in the local project, it will +download them from `Google fonts `_. You can try others (bear in mind +that font names *are* case-sensitive.) + +.. warning:: + + rinohtype is not able to parse all font properties, and you may run into an error with some + typefaces. diff --git a/doc/tutorial/content.rst b/doc/tutorial/content.rst new file mode 100644 index 000000000..910626b58 --- /dev/null +++ b/doc/tutorial/content.rst @@ -0,0 +1,159 @@ +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. + + +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 +`_. Rename it to ``rhino.png`` and +place it in the root of your Sphinx project. In ``plans.rst``, add:: + + .. 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). diff --git a/doc/tutorial/customisation.rst b/doc/tutorial/customisation.rst new file mode 100644 index 000000000..2f69a9bc5 --- /dev/null +++ b/doc/tutorial/customisation.rst @@ -0,0 +1,72 @@ +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 we'll use the popular +`Furo `_ theme. Install Furo in your virtual environment:: + + pip install furo + +then in ``conf.py``, edit the ``html_theme`` setting, to:: + + html_theme = 'furo' + +Rebuild the HTML to see the effect. + + +PDF +--- + +Customisation of PDF output is a little more complex. We need to do three things. + +First, apply some rinoh configuration in ``conf.py``, with :confval:`rinoh_documents`:: + + 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. diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst new file mode 100644 index 000000000..5a5533990 --- /dev/null +++ b/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 diff --git a/doc/tutorial/install.rst b/doc/tutorial/install.rst new file mode 100644 index 000000000..d886ed9fb --- /dev/null +++ b/doc/tutorial/install.rst @@ -0,0 +1,51 @@ +Installation +============ + +All work will take place in a Python virtual environment. + +First, create a directory for your project, then a virtual environment within +it, and activate the virtual environment:: + + mkdir rinoh-tutorial + cd rinoh-tutorial + python -m venv .env + source .env/bin/activate + +Install rinotype:: + + pip install Sphinx rinohtype + + +Start a new Sphinx project +-------------------------- + +Use ``sphinx-quickstart`` to bootstrap a new project:: + + sphinx-quickstart . + +You'll need to answer a few questions. Name the project ``All about me`` when +asked. You can accept any defaults for other questions. Sphinx will create a +set of files ready for you to start working with. + +The virtual environment for this project is inside the project directory, so to prevent Sphinx +from trying to process everything inside ``.env``, add it to the list of files and directories +to be excluded, which you will find in ``conf.py``:: + + exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.env'] + +Test your project, by running:: + + make html + +Sphinx will build the HTML version of the (rather empty) site and inform you +that it can be found in ``_build/html``. Open the ``index.html`` file inside +there in your browser. + +Do the same with rinohtype's Sphinx builder:: + + make rinoh + +which should create a PDF version of the project, as +``_build/rinoh/allaboutme.pdf``. We now have a working project that generates +both HTML and PDF versions of the content, and we can begin developing it +further.