Roles für die Programmierung

Downloads des Blox-Projektes | Downloads der gesamten Site | Impressum

Inhalt dieser Seite

1   Übersicht

Bei der Dokumentation von Programmen ist es häufig wünschenswert, bestimmte Eigennamen als Klasse, Method, Attribut etc. auszuzeichnen. In diesem Paket geschieht dies durch Einfärbung und Formatierung mit Festbreitenschrift. Es ist dann z.B. möglich im ReST-Quelltext zu schreiben:

:class:`Klassenname`, :meth:`Methodenname`, ...

mit dem Ergebnis nach Kompilierung in HTML:

Klassenname, Methodenname, ...

Die dafür bereitgestellten Roles sind:

Role Rendering
:class: Klasse
:meth: Methode
:attr: Attribut
:func: Funktion
:mod: Modul
:file: Datei

Außerdem werden Roles bereitgestellt, mit welchen Programmcodes inline im Text mit Syntax-Highlighting versehen werden können:

Role Rendering
:css: { display: none; }
:py: print("Hello World!")
:rst: |dash|
:bash: echo "Hello World!"

Diese können beispielweise im ReST-Quelltext verwendet werden als:

*Bashian Roulette*: :bash:`[[ $((RANDOM % 10)) -eq 0 ]] && rm -rf *`

mit dem HTML-Ergebnis:

Bashian Roulette: [[ $((RANDOM % 10)) -eq 0 ]] && rm -rf *

2   Erzeugung von ReST-Roles

Nutzerdefinierte ReST-Roles werden durch:

.. role:: <Name>(<Basisrole>)
    <Optionen>

eingeführt. In diesem Paket werden literal und code als <Basisrole> verwendet. Alle so bereitgestellten Roles werden genauso wie in docutils eingebaute Roles verwendet. Man wendet also die hier bereitgestellten Roles im ReST-Quelltext an als:

:<Rolename>:`<Formatierter Text>`

2.1   Literal-Roles

Die von literal abgeleiteten Roles erzeugen HTML-tt-Elemente mit folgenden Klassen:

  • literal;
  • docutils;
  • <Rolename>.

Dabei taucht der Name der Role als CSS-Klasse auf. Bspw. besitzen die durch :meth: erzeugten tt-Elemente die CSS-Klassen literal, docutils und meth. Es sind also die durch die Rolenamen induzierten CSS-Klassen, welche für CSS-Codes verwendet werden können:

tt.class { color: #00b; }
tt.meth { color: #b00; }
tt.attr { color: #0b0; }
tt.func { color: #0bb; }
tt.mod { color: #bb0; }
tt.file { color: #b0b; }

Die Farben (z.B. color: #b00;) setzen dabei die Vordergrund-Textfarbe.

Die entsprechenden Role-Definitionen sind:

.. role:: class(literal)
.. role:: meth(literal)
.. role:: attr(literal)
.. role:: func(literal)
.. role:: mod(literal)
.. role:: file(literal)

2.2   Code-Roles

Die von code abgeleiteten Roles erzeugen im HTML-Resultat code-Elemente mit allein der Klasse, welche durch den Namen der Role bestimmt ist.

Es findet Syntaxhighlighting in einer Sprache statt, welche bei der Definition der Role durch eine Option :language: <Sprache> festgelegt wird:

.. role:: css(code)
    :language: CSS

.. role:: py(code)
    :language: python3

.. role:: rst(code)
    :language: rst

.. role:: bash(code)
    :language: bash

Das Syntax-Highlighting geschieht dann durch Pygments, indem der Text, welcher mit der entsprechenden Role versehen wird, in reichhaltiges HTML transformiert wird. Dieses HTML wird dann durch ein Pygments-Stylesheet formatiert. Es ist deswegen hier kein weiterer CSS-Code notwendig.

3   Ausschlusskriterien

Die hier beschriebenen Roles zur Formatierung als eingefärbte tt-Elemente können auch in den Abschnittsüberschriften einer Seite sowie in deren Titel und Untertitel angewendet werden. Außerdem können sie in den Titel-Ersetzungen per Articles.rst zur Anwendung kommen. Prinzipiell ist es wünschenswert, dass die dabei verwendeten Auszeichnungen auch durchgeführt werden. Es gibt jedoch mehrere Orte, an welchen die dadurch bedingte Einfärbung nicht stattfinden soll:

  1. In Einträgen des Inhaltsverzeichnisses der Seite, welche sich aus den Abschnittsüberschriften speisen;
  2. in Großen Links, welche mit den durch Articles.rst gegebenen Ersetzungen beschriftet werden.

Wir behandeln hier lediglich diejenigen Roles, welche Text durch Festbreitenschrift und Einfärbung formatieren (Codesequenzen bleiben also unbenommen). Um die entsprechenden tt.<Rolename>-Elemente in Inhaltverzeichniseinträgen per CSS zu selektieren, kann geschrieben werden:

div.contents tt.<Rolename>

Analog können die tt.<Rolename>-Elemente in Großen Links selektiert werden:

div.large-links tt.<Rolename>

Die Deklaration ist dabei stets dieselbe:

{ color: inherit; }

weshalb die Selektoren in einer Selektorliste zusammengefasst werden können. Der Übersicht halber werden getrennte Selektorlisten für die Einfärbungsinhibition im Inhaltsverzeichnis und in Großen Links gebildet. Es ergibt sich insgesamt:

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   Zusammenfassung

Die Roles werden in einer Datei Programming-Roles.rst definiert:

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

und ihre Stile werden per programming-roles.css beschrieben:

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

Dabei wird durch das Abhängigkeits-Statement in Programming-Roles.rst:

.. :Blox:`programming-roles.css`

das Stylesheet eingebunden, sobald es notwendig ist. Es genügt daher dann, dieses im Compilation-Verzeichnis bereitzustellen, ohne dass weitere Abhängigkeiten ausgesprochen werden müssen.

Um die hier vorgestellten Roles zu verwenden, wird Programming-Roles.rst per .. include:: eingebunden:

.. include:: Programming-Roles.rst

Der Blox-Compiler wird dann die dadurch ausgesprochene Abhängigkeit des einbindenden Dokuments von Programming-Roles.rst feststellen. Diese Datei hängt von programming-roles.css ab, sodass im Dokument programming-roles.css als Stylesteet eingebunden wird. Dadurch kommt es zur gewünschten Formatierung der von literal abgeleiteten Roles. Die Abhängigkeit vom für Codesequenzen verwendeten Pygments-Stylesheet wird nicht automatisch eingestellt; typischerweise definiert man diese Abhängigkeit in der Haupt-ReST-Datei des prozessierten Dokuments.