diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 1eb0a03da..17e5136e2 100644 --- a/.github/workflows/tests.yml +++ b/.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 }}': diff --git a/CHANGES.rst b/CHANGES.rst index 416f9b045..5fceeb79f 100644 --- a/CHANGES.rst +++ b/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 diff --git a/README.rst b/README.rst index 8138da2f9..5f98c7d57 100644 --- a/README.rst +++ b/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 diff --git a/doc/conf.py b/doc/conf.py index 669fcc978..d6b912c72 100644 --- a/doc/conf.py +++ b/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 diff --git a/doc/intro.rst b/doc/intro.rst index 9ccf7246d..ad6d233fe 100644 --- a/doc/intro.rst +++ b/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 diff --git a/doc/manual.rst b/doc/manual.rst index 5ae060399..9af4c555a 100644 --- a/doc/manual.rst +++ b/doc/manual.rst @@ -5,6 +5,7 @@ :hidden: intro + showcase install quickstart basicstyling diff --git a/doc/rinohtype.rts b/doc/rinohtype.rts index 235e7b80a..f56be466c 100644 --- a/doc/rinohtype.rts +++ b/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] diff --git a/doc/showcase.rst b/doc/showcase.rst new file mode 100644 index 000000000..f6becc2b6 --- /dev/null +++ b/doc/showcase.rst @@ -0,0 +1,51 @@ +.. _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` was styled by means 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 diff --git a/doc/showcase/Odpisy.pdf b/doc/showcase/Odpisy.pdf new file mode 100644 index 000000000..27a52db69 Binary files /dev/null and b/doc/showcase/Odpisy.pdf differ diff --git a/doc/showcase/Odpisy.png b/doc/showcase/Odpisy.png new file mode 100644 index 000000000..20c5de93d Binary files /dev/null and b/doc/showcase/Odpisy.png differ diff --git a/noxfile.py b/noxfile.py index 36acdb4bd..96af08fc1 100644 --- a/noxfile.py +++ b/noxfile.py @@ -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)