This package permits placing in the footer of a page an itemisation of the key colours defined in Programming Roles. For this the following files are used:
With these files it is then possible to write:
.. include:: Colourkeys.rst .. container:: colour-keys |class-key| |meth-key| |attr-key| |func-key| |mod-key| |file-key|
One needs to list here only those items which are actually relevant for the document.
The colour-keys container can be placed e.g. in the footer. A typical footer definition thus runs:
.. footer:: .. container:: colour-keys |class-key| |meth-key| (...) (...)
A colour key itemisation defined with the help of this package can be found in the footer of this page.
The Replacements (e.g. |class-key|) are provided by
Colourkeys.rst. In the English version the content of this file
runs:
Colourkeys.rst (en)
.. :Blox:`colourkeys.css` .. |class-key| replace:: :class:`Class` .. |meth-key| replace:: :meth:`Method` .. |attr-key| replace:: :attr:`Attribute` .. |func-key| replace:: :func:`Function` .. |mod-key| replace:: :mod:`Module` .. |file-key| replace:: :file:`File`
and in the German variant:
Colourkeys.rst (de)
.. :Blox:`colourkeys.css` .. |class-key| replace:: :class:`Klasse` .. |meth-key| replace:: :meth:`Methode` .. |attr-key| replace:: :attr:`Attribut` .. |func-key| replace:: :func:`Funktion` .. |mod-key| replace:: :mod:`Modul` .. |file-key| replace:: :file:`Datei`
The Colourkeys.rst files contain thereby a dependency mark:
.. :Blox:`colourkeys.css`
By this, the style described by colourkeys.css is applied to the respective document as soon as Colourkeys.rst is included.
The replacements can be used directly:
|class-key| |meth-key| |attr-key| |func-key| |mod-key| |file-key|
with the result:
Class Method Attribute Function Module File
In the actual application precisely the same replacements are used
(|class-key| etc.), but the result is styled by CSS in another way.
The itemisation shall have the following visual appearance:
The div.colour-keys section defined by:
.. container:: colour-keys (...)
is formatted via:
div.colour-keys { display: flex; column-gap: 1ex; justify-content: flex-end; margin-top: 1ex; margin-bottom: 1ex; }
The instruction block of this rule is separated in two sections:
div.colour-keys item as a
horizontal flex container (display: flex). Between the
individual elements 1ex space is left (column-gap: 1ex)
and in principle the contained elements are right-justified
(justify-content: flex-end).1ex; this
is suitable for use in the footer.All colour roles to be itemised, as defined by Programming Roles, are derived from literal and thus create tt elements. The CSS code in colourkeys.css to adorn the entries of the itemisation each with a border uses this by specifying:
div.colour-keys tt { border: thin solid currentColor; border-radius: 1em; padding: 0.5ex 1.5ex; }
Here, all tt elements in the colour-keys container created by the roles
are selected. border: thin solid currentColor creates around these
tt elements a thin solid border. The specific roles
(:class:, :meth: etc.) set the text colour, which is inherited
to the border by using currentColor. The declaration
border-radius: 1em rounds the borders at the left and right ends.
padding: 0.5ex 1.5ex separates the border lines of the singular entries
from their label text at the top/bottom sides by 0.5ex, and at the
left/right ends by 1.5ex. The vertical padding has been decided at
first, and the horizontal padding has then been chosed such that the resulting
line is not overlapping with the text.
It results for the entire style sheet:
colourkeys.css
/* Developed since: July 2024 * Based on work dating back to pre-July 2023. */ div.colour-keys { display: flex; column-gap: 1ex; justify-content: flex-end; margin-top: 1ex; margin-bottom: 1ex; } div.colour-keys tt { border: thin solid currentColor; border-radius: 1em; padding: 0.5ex 1.5ex; }
For provisioning the files of this package the following rules apply:
The files made accessible in this way need to be included into the project by the corresponding .blox files. The purpose of the ReST files should be thereby be defined as /rst/, and for the CSS file /css/ is used. While the purpose definition of the ReST files is rather for the sake of completeness, the CSS file must be provided with /css/, such that it is included as a stylesheet when required. The compiler will then respect the dependency on the style sheet specified in the Colourkeys.rst files when the project is compiled.