From ded5f0fc1a19be2fa5ae9a1464e1d8a5a8c16fec Mon Sep 17 00:00:00 2001 From: Daniele Procida Date: Tue, 24 May 2022 09:22:01 +0100 Subject: [PATCH 1/6] Started a tutorial --- doc/index.rst | 24 ++++++++--- doc/manual.rst | 2 +- doc/tutorial/content.rst | 61 ++++++++++++++++++++++++++++ doc/tutorial/custom-template.rst | 18 +++++++++ doc/tutorial/customisation.rst | 69 ++++++++++++++++++++++++++++++++ doc/tutorial/index.rst | 20 +++++++++ doc/tutorial/install.rst | 48 ++++++++++++++++++++++ 7 files changed, 236 insertions(+), 6 deletions(-) create mode 100644 doc/tutorial/content.rst create mode 100644 doc/tutorial/custom-template.rst create mode 100644 doc/tutorial/customisation.rst create mode 100644 doc/tutorial/index.rst create mode 100644 doc/tutorial/install.rst 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..cf54d8ef2 100644 --- a/doc/manual.rst +++ b/doc/manual.rst @@ -1,10 +1,10 @@ - .. toctree:: :caption: User Manual :maxdepth: 2 :hidden: intro + manual/index install quickstart basicstyling diff --git a/doc/tutorial/content.rst b/doc/tutorial/content.rst new file mode 100644 index 000000000..d034724dd --- /dev/null +++ b/doc/tutorial/content.rst @@ -0,0 +1,61 @@ +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 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. + +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. + + Long-term plans + --------------- + + And perhaps you have some that will come later on. + +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 + +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). + +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/custom-template.rst b/doc/tutorial/custom-template.rst new file mode 100644 index 000000000..690c80f94 --- /dev/null +++ b/doc/tutorial/custom-template.rst @@ -0,0 +1,18 @@ +Creating a custom template +=========================== + +To recap what we've built so far: + +* first, we have a Sphinx project containing some content across multiple + sections +* as well as Sphinx's built-in HTML rendering, rinohtype includes a builder + that produces a PDF version +* in ``conf.py``, we have pointed rinohtype at a local template configuration + file, ``my-article.rtt`` +* the ``my-article.rtt`` template configuration does two things: it tells + rinohtype to use use the built-in ``article`` template, and to use a custom + stylesheet, ``allaboutme.rts``, that extends the built-in ``sphinx`` + stylesheet + + +Have a look at the contents of the :ref:`Sphinx style sheet`. diff --git a/doc/tutorial/customisation.rst b/doc/tutorial/customisation.rst new file mode 100644 index 000000000..d6e38082a --- /dev/null +++ b/doc/tutorial/customisation.rst @@ -0,0 +1,69 @@ +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 colors 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. diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst new file mode 100644 index 000000000..75d8bcaa9 --- /dev/null +++ b/doc/tutorial/index.rst @@ -0,0 +1,20 @@ +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 + custom-template diff --git a/doc/tutorial/install.rst b/doc/tutorial/install.rst new file mode 100644 index 000000000..1e476b40c --- /dev/null +++ b/doc/tutorial/install.rst @@ -0,0 +1,48 @@ +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 rinohtype + +You'll notice that Sphinx and various other components are installed as +dependencies of 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. + +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. From a99289e952a444a34d81bae88f8086718418715b Mon Sep 17 00:00:00 2001 From: Daniele Procida Date: Tue, 24 May 2022 09:28:01 +0100 Subject: [PATCH 2/6] Improved the tutorial --- CHANGES.rst | 5 ++ doc/tutorial/configuring-stylesheet.rst | 43 +++++++++ doc/tutorial/content.rst | 113 +++++++++++++++++++++++- doc/tutorial/custom-template.rst | 18 ---- doc/tutorial/customisation.rst | 17 ++-- doc/tutorial/index.rst | 4 +- 6 files changed, 168 insertions(+), 32 deletions(-) create mode 100644 doc/tutorial/configuring-stylesheet.rst delete mode 100644 doc/tutorial/custom-template.rst diff --git a/CHANGES.rst b/CHANGES.rst index 8466e634d..159a73daf 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: + +* 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/tutorial/configuring-stylesheet.rst b/doc/tutorial/configuring-stylesheet.rst new file mode 100644 index 000000000..b12a164b6 --- /dev/null +++ b/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. diff --git a/doc/tutorial/content.rst b/doc/tutorial/content.rst index d034724dd..875123511 100644 --- a/doc/tutorial/content.rst +++ b/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 + `_. 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 diff --git a/doc/tutorial/custom-template.rst b/doc/tutorial/custom-template.rst deleted file mode 100644 index 690c80f94..000000000 --- a/doc/tutorial/custom-template.rst +++ /dev/null @@ -1,18 +0,0 @@ -Creating a custom template -=========================== - -To recap what we've built so far: - -* first, we have a Sphinx project containing some content across multiple - sections -* as well as Sphinx's built-in HTML rendering, rinohtype includes a builder - that produces a PDF version -* in ``conf.py``, we have pointed rinohtype at a local template configuration - file, ``my-article.rtt`` -* the ``my-article.rtt`` template configuration does two things: it tells - rinohtype to use use the built-in ``article`` template, and to use a custom - stylesheet, ``allaboutme.rts``, that extends the built-in ``sphinx`` - stylesheet - - -Have a look at the contents of the :ref:`Sphinx style sheet`. diff --git a/doc/tutorial/customisation.rst b/doc/tutorial/customisation.rst index d6e38082a..cd766788f 100644 --- a/doc/tutorial/customisation.rst +++ b/doc/tutorial/customisation.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. diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 75d8bcaa9..5a5533990 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.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 From 8eb53440efb576787915bacc06798f297223a166 Mon Sep 17 00:00:00 2001 From: Daniele Procida Date: Fri, 10 Jun 2022 19:26:02 +0100 Subject: [PATCH 3/6] Fixed error in manual.rst --- doc/manual.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual.rst b/doc/manual.rst index cf54d8ef2..375d73f47 100644 --- a/doc/manual.rst +++ b/doc/manual.rst @@ -4,7 +4,7 @@ :hidden: intro - manual/index + tutorial/index install quickstart basicstyling From 89c4483e4149beb41a526b89b9db761556fc2aef Mon Sep 17 00:00:00 2001 From: Daniele Procida Date: Fri, 10 Jun 2022 21:01:29 +0100 Subject: [PATCH 4/6] Fixed some tutorial errors --- doc/tutorial/content.rst | 15 ++++----------- doc/tutorial/install.rst | 11 +++++++---- 2 files changed, 11 insertions(+), 15 deletions(-) diff --git a/doc/tutorial/content.rst b/doc/tutorial/content.rst index 875123511..910626b58 100644 --- a/doc/tutorial/content.rst +++ b/doc/tutorial/content.rst @@ -47,12 +47,6 @@ entire contents of the file with the following (edit the text to your taste):: 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:: @@ -101,11 +95,10 @@ Add a new file, ``plans.rst``, containing:: 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. +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 diff --git a/doc/tutorial/install.rst b/doc/tutorial/install.rst index 1e476b40c..d886ed9fb 100644 --- a/doc/tutorial/install.rst +++ b/doc/tutorial/install.rst @@ -13,10 +13,7 @@ it, and activate the virtual environment:: Install rinotype:: - pip install rinohtype - -You'll notice that Sphinx and various other components are installed as -dependencies of rinohtype. + pip install Sphinx rinohtype Start a new Sphinx project @@ -30,6 +27,12 @@ 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 From 2c0a8f5b791927a66e2789eff7e4f0ecd46500d0 Mon Sep 17 00:00:00 2001 From: Daniele Procida Date: Fri, 10 Jun 2022 21:47:43 +0100 Subject: [PATCH 5/6] Fixed some issues in the tutorial --- CHANGES.rst | 2 +- doc/tutorial/configuring-stylesheet.rst | 4 ++-- doc/tutorial/customisation.rst | 12 ++++++++---- 3 files changed, 11 insertions(+), 7 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index 159a73daf..4fc34b501 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -84,7 +84,7 @@ Fixed: and importlib_metadata 3.6) * Handle deprecation of distutils in Python 3.10 (use the packaging package) -Documentation: +Documentation (Daniele Procida): * Started a new Tutorial section. * Rewrote the first four paragraphs of the home page, to say: what rinohtype diff --git a/doc/tutorial/configuring-stylesheet.rst b/doc/tutorial/configuring-stylesheet.rst index b12a164b6..96d394f79 100644 --- a/doc/tutorial/configuring-stylesheet.rst +++ b/doc/tutorial/configuring-stylesheet.rst @@ -7,7 +7,7 @@ To recap what we've built so far: * 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: + ``conf.py``, and tells rinohtype to: * use the built-in ``article`` template * apply a stylesheet, ``allaboutme.rts``, that extends the built-in @@ -24,7 +24,7 @@ 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 +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. diff --git a/doc/tutorial/customisation.rst b/doc/tutorial/customisation.rst index cd766788f..2f69a9bc5 100644 --- a/doc/tutorial/customisation.rst +++ b/doc/tutorial/customisation.rst @@ -5,8 +5,12 @@ 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:: +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' @@ -16,9 +20,9 @@ Rebuild the HTML to see the effect. PDF --- -The PDF customisation is a little more complex. We need to do three things. +Customisation of PDF output is a little more complex. We need to do three things. -First, apply some rinoh configuration in ``conf.py``:: +First, apply some rinoh configuration in ``conf.py``, with :confval:`rinoh_documents`:: rinoh_documents = [ { From 35154f068c27de9e8f2813785150d4c095e1902e Mon Sep 17 00:00:00 2001 From: Daniele Procida Date: Sat, 11 Jun 2022 10:13:45 +0100 Subject: [PATCH 6/6] Expanded basic styling chapter in tutorial --- doc/tutorial/configuring-stylesheet.rst | 51 +++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/doc/tutorial/configuring-stylesheet.rst b/doc/tutorial/configuring-stylesheet.rst index 96d394f79..6e520250e 100644 --- a/doc/tutorial/configuring-stylesheet.rst +++ b/doc/tutorial/configuring-stylesheet.rst @@ -15,6 +15,10 @@ To recap what we've built so far: ---- + +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. @@ -41,3 +45,50 @@ 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.