When documenting programs it is often desirable to mark up certain proper names as class, method, attribute etc. In this package this happens by colouring and by formatting using a fixed-width font. Is is then possible to write in the ReST sources e.g.:
:class:`Class Name`, :meth:`Method Name`, ...
with the result after compiling as HTML:
Class name, Method Name, ...
The roles provided for this are:
| Role | Rendering |
|---|---|
:class: |
Class |
:meth: |
Method |
:attr: |
Attribute |
:func: |
Function |
:mod: |
Module |
:file: |
File |
Besides, roles to format program codes inline in continuous text with syntax highlighting are provided:
| Role | Rendering |
|---|---|
:css: |
{ display: none; } |
:py: |
print("Hello World!") |
:rst: |
|dash| |
:bash: |
echo "Hello World!" |
These can be used in ReST sources e.g. as:
*Bashian Roulette*: :bash:`[[ $((RANDOM % 10)) -eq 0 ]] && rm -rf *`
with the HTML result:
Bashian Roulette: [[ $((RANDOM % 10)) -eq 0 ]] && rm -rf *
User-defined ReST roles are introduced by:
.. role:: <Name>(<Base Role>) <Options>
In this package literal and code are used as <Base Role>. All roles provided are used just as roles built into docutils. Thus, one applies the roles provided here in the ReST source text as:
:<Role Name>:`<Formatted Text>`
The roles derived from literal produce HTML tt elements with the following classes:
Here, the name of the role shows up as CSS class. For example, the
tt elements created by :meth: possess the CSS classes
literal, docutils and meth. Thus, the CSS classes induced by
the role name can be used for the CSS codes:
tt.class { color: #00b; } tt.meth { color: #b00; } tt.attr { color: #0b0; } tt.func { color: #0bb; } tt.mod { color: #bb0; } tt.file { color: #b0b; }
Here, the colours (e.g. color: #b00;) specify the foreground text
colour.
The corresponding role definitons are:
.. role:: class(literal) .. role:: meth(literal) .. role:: attr(literal) .. role:: func(literal) .. role:: mod(literal) .. role:: file(literal)
The roles derived from code produce in the resulting HTML code elements solely with the class which is given by the name of the role.
Thereby syntax highlighting takes place in a language which is determined
during the definition of the role by a :language: <Language> option:
.. role:: css(code) :language: CSS .. role:: py(code) :language: python3 .. role:: rst(code) :language: rst .. role:: bash(code) :language: bash
The syntax highlighting is performed by Pygments, by transforming the text provided with the respective role into rich HTML. This HTML is then formatted by a pygments stylesheet. Thus, no further CSS code is required here.
The roles described here to format using coloured tt elements can also be applied in section headings of a page as well as in the title line and subtitle. Furthermore, they might be used in the title replacements per Articles.rst. In principle, it is desirable that the markups used there are also applied. However, there are a few places where the colouring induced in this way shall not take place:
We cover here only those roles, which format text by fixed-width font choice and by colouring (code sequence thus are not affected). To select the corresponding tt.<Role Name> element in entries of the table of contents per CSS, it can be written:
div.contents tt.<Rolename>
Analogous, the tt.<Role name> elements in large links can be selected by:
div.large-links tt.<Rolename>
The declaration is thereby always the same:
{ color: inherit; }
Because of this, the selectors can be collected into a selector list. For the sake of overview, separate selector lists are created for inhibiting colouring in the table of contents and in large links. Overall it results:
div.contents tt.class, div.contents tt.meth, div.contents tt.attr, div.contents tt.func, div.contents tt.mod, div.contents tt.file { color: inherit; } div.large-links tt.class, div.large-links tt.meth, div.large-links tt.attr, div.large-links tt.func, div.large-links tt.mod, div.large-links tt.file { color: inherit; }
The roles are defined in a file Programming-Roles.rst:
Programmming-Roles.rst
.. :Blox:`programming-roles.css` .. role:: class(literal) .. role:: meth(literal) .. role:: attr(literal) .. role:: func(literal) .. role:: mod(literal) .. role:: file(literal) .. role:: css(code) :language: CSS .. role:: py(code) :language: python3 .. role:: rst(code) :language: rst .. role:: bash(code) :language: bash
and their styles are described by programming-roles.css:
programming-roles.css
tt.class { color: #00b; } tt.meth { color: #b00; } tt.attr { color: #0b0; } tt.func { color: #0bb; } tt.mod { color: #bb0; } tt.file { color: #b0b; } div.contents tt.class, div.contents tt.meth, div.contents tt.attr, div.contents tt.func, div.contents tt.mod, div.contents tt.file { color: inherit; } div.large-links tt.class, div.large-links tt.meth, div.large-links tt.attr, div.large-links tt.func, div.large-links tt.mod, div.large-links tt.file { color: inherit; }
Here, the dependency statement in Programming-Roles.rst:
.. :Blox:`programming-roles.css`
leads to the inclusion of the style sheet when it is required. Therefore, it suffices to provide the style sheet in the compilation directory, without any further ado to declare dependencies.
To use the roles introduced here, Programming-Roles.rst is to be
included by the .. include:: directive:
.. include:: Programming-Roles.rst
The Blox compiler willl recognise the hereby defined dependency of the including document on Programming-Roles.rst. This file in turn depends on programming-roles.css, such that in the document programming-roles.css will be included as a style sheet. By this, the desired formatting of the roles derived from literal takes place. The dependency on the Pygments style sheet used for code sequences is not set up automatically; typically this dependency is defined in the main ReST file of the document processed.