Programming Roles

Downloads of the Blox Project | Downloads of the entire Site | Imprint

Contents of this Page

1   Overview

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 *

2   Creation of ReST Roles

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>`

2.1   Literal Roles

The roles derived from literal produce HTML tt elements with the following classes:

  • literal;
  • docutils;
  • <Role Name>.

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)

2.2   Code Roles

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.

3   Exclusion Criterions

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:

  1. In entries of a page's table of contents, which are defined by the section headings;
  2. in large links, labelled with replacements defined by Articles.rst.

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; }

4   Summary

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.