Docs: add showcase section with Lekis example

Author: brechtm

.github/workflows/tests.yml

@@ -35,6 +35,8 @@ jobs:
     - uses: actions/checkout@v3
       with:
         submodules: true
+    - name: Get tag
+      uses: olegtarasov/get-tag@v2
     - name: Install Python ${{ env.current_python }}
       uses: actions/setup-python@v4
       with:
@@ -294,7 +296,7 @@ jobs:
       with:
         submodules: true
     - name: Get tag
-      uses: olegtarasov/get-tag@v2.1
+      uses: olegtarasov/get-tag@v2
     - name: Install Python ${{ env.current_python }}
       uses: actions/setup-python@v4
       with:
@@ -305,7 +307,7 @@ jobs:
     - name: Get package version from Poetry
       run: echo "PKG_VERSION=$(poetry version --short)" >> $GITHUB_ENV
     - name: Check whether the tag matches the package version
-      uses: jannekem/run-python-script-action@utilities
+      uses: jannekem/run-python-script-action@v1
       with:
         script: |
           if '${{ env.GIT_TAG_NAME }}' != 'v${{ env.PKG_VERSION }}':

CHANGES.rst

@@ -17,6 +17,11 @@ Release History
 Release 0.5.5 (in development)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Documentation changes:
+
+* A showcase section was added to the manual to show examples of documents that
+  can be produces by rinohtype.
+
 New Features:
 
 * Enumerated list item labels now also respect the *number_separator* style

README.rst

@@ -28,8 +28,13 @@ rinohtype
 
 rinohtype is a batch-mode document processor. It renders structured documents
 to PDF based on a document template and a style sheet. An important design goal
-of rinohtype is make document layout and style customization user-friendly. See
-the documentation_ to learn how to customize the style of your document.
+of rinohtype is make document layout and style customization user-friendly. Have
+a look at the showcase_ to get an idea of the level of customization that is
+possible. See the documentation_ to learn how to customize the style of your
+document.
+
+.. _showcase: https://www.mos6581.org/rinohtype/master/showcase.html
+.. _documentation: http://www.mos6581.org/rinohtype/master/
 
 
 Call for Contributions
@@ -92,7 +97,6 @@ a look at the `rinohtype manual`_ for an example of the output.
 There is also a commercial DITA_ frontend, but it's development is currently
 on hold. Please `contact me`_ if you are interested in testing it.
 
-.. _documentation: http://www.mos6581.org/rinohtype/master/
 .. _create a ticket: https://github.com/brechtm/rinohtype/issues/new/choose
 .. _Google Fonts: https://fonts.google.com
 .. _reStructuredText: http://docutils.sourceforge.net/rst.html

doc/conf.py

@@ -14,6 +14,7 @@
 # serve to show the default.
 
 
+import os
 import time
 
 try:
@@ -40,13 +41,14 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
     'sphinx.ext.coverage',
     'sphinx.ext.doctest',
+    'sphinx.ext.extlinks',
+    'sphinx.ext.githubpages',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
     'sphinx.ext.todo',
-    'sphinx.ext.autosummary',
-    'sphinx.ext.githubpages',
     'sphinx_immaterial',
     'sphinxcontrib.autoprogram',
 ]
@@ -124,6 +126,12 @@
 intersphinx_mapping = {'python': ('https://docs.python.org/3', None),
                        'sphinx': ('https://www.sphinx-doc.org/en/master', None)}
 
+GIT_TAG = os.environ.get('GIT_TAG_NAME')
+SHOWCASE_URL = (f'http://www.mos6581.org/rinohtype/{GIT_TAG}/showcase/%s'
+                if GIT_TAG else './showcase/%s')
+
+extlinks = {'showcase': (SHOWCASE_URL, '%s')}
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

doc/intro.rst

@@ -105,5 +105,3 @@ database or other data sources. When parsing the document tree from a
 structured document format, a templating engine like Jinja2_ can be used.
 
 .. _Jinja2: http://jinja.pocoo.org
-
-.. todo:: sample documents

doc/manual.rst

@@ -5,6 +5,7 @@
     :hidden:
 
     intro
+    showcase
     install
     quickstart
     basicstyling

doc/rinohtype.rts

@@ -227,7 +227,7 @@ number_format=None
 font_color=#4d4d4d
 
 [external hyperlink]
-base=internal hyperlink
+font_color=#004d4d
 
 [broken hyperlink]
 font_color=#ff0000
@@ -297,6 +297,39 @@ font_slant=italic
 base=body
 space_above=1pt
 
+[image]
+space_above=10pt
+horizontal_align=CENTER
+
+[figure]
+space_above=10pt
+space_below=12pt
+
+[figure image]
+base=image
+keep_with_next=true
+
+[caption : Caption]
+base=default
+font_size=9pt
+line_spacing=Fixed(10pt)
+indent_first=0pt
+space_above=4pt
+space_below=0pt
+text_align=CENTER
+label_suffix=' '
+
+[figure caption]
+base=caption
+
+[figure legend]
+margin_left=30pt
+
+[figure legend paragraph]
+base=caption
+space_above=5pt
+text_align=LEFT
+
 # (Sphinx) object descriptions
 
 [object description]

doc/showcase.rst

@@ -0,0 +1,50 @@
+.. _showcase:
+
+Showcase
+========
+
+Some examples of PDF documents produced by rinohtype are collected here. This
+section mainly serves to give users an idea of the level of customization that
+is achievable by means of custom templates and style sheets.
+
+
+Lekis
+-----
+
+:showcase:`Odpisy.pdf` makes use of both a custom template and style sheet. The
+custom template (Python) and configuration (INI file):
+
+- configures Czech as the document's language, which prevents a line break
+  after specific words (following Czech typography rules)
+- defines custom title (with vector logo) and colophon pages
+- sets a background for content pages, marking the page header
+- defines a custom back page, listing company contact details
+
+Actually, there are two template configuration files: a base configuration and
+one for a special type of documents. The latter inherits from the base template
+configuration and only overrides what needs changing. In this case, it omits
+the table of contents part from the document. The PDF linked to above is an
+example of such a document.
+
+
+.. magick montage -density 20 "doc/showcase/Odpisy.pdf[0,2,5]" -background grey
+    -tile x1 -border 4 -bordercolor white -geometry +0+0 doc/showcase/Odpisy.png
+.. figure:: showcase/Odpisy.png
+
+   Some pages from :showcase:`Odpisy.pdf`
+
+
+A single style sheet is used for both types of documents. It does not specify
+the Sphinx style sheet included with rinohtype as a base stylesheet so as to
+avoid unexpected changes in the document style in case the Sphinx style sheet
+is updated in a future rinohtype release. The style sheet defines:
+
+- the ``[VARIABLES]`` section defines monospaced, serif and sans-serif
+  typefaces and a set of key colors that are referenced in style definitions
+- custom 'numbering' for headings (square glyph) and bullet lists (fast forward
+  glyph)
+- a top border for certain headings
+- custom in-line titles (in-line images or specific font glyphs) for
+  admonitions
+- coloured styling for the ``menuselection`` role
+- small-capital styling for keyboard shortcuts

doc/showcase/Odpisy.pdf

@@ -56,8 +56,12 @@ def build_docs(session):
                                     'sphinxcontrib-autoprogram'])
     session.chdir('doc')
     session.run('python', 'build.py', *session.posargs)
-    for pdf in glob.glob("_build/rinoh/*.pdf"):
-        shutil.copy(pdf, "_build/html")
+    # copy 'showcase' directory to the HTML output directory
+    shutil.copytree('showcase', '_build/html/showcase', dirs_exist_ok=True)
+    # copy PDF docs to the HTML output directory
+    for pdf in glob.glob('_build/rinoh/*.pdf'):
+        shutil.copy(pdf, '_build/html')
+
 
 
 @nox_poetry.session(python=PYTHONS)