Software in AsciiDoc dokumentieren

In der technischen Dokumentation sind Code-Beispiele essenziell. AsciiDoc bietet eine einfache und flexible Möglichkeit, Code sowohl innerhalb eines Satzes als auch in mehrzeiligen Code-Blöcken darzustellen.

So fügen Sie Code Blöcke ein

[source,python]
----
def hello():
    print("Hallo, AsciiDoc!")

hello()
----

  • [source,python] definiert die Sprache für Syntax-Highlighting.

  • ---- umschließt den Code-Block.

Callouts für Erklärungen

AsciiDoc ermöglicht es, Codezeilen direkt mit Callouts zu versehen, um einzelne Teile zu erklären:

[source,python]
----
def hello(): // <1>
    print("Hallo, AsciiDoc!") // <2>

hello() // <3>
----
<1> Definiert die Funktion `hello`
<2> Gibt eine Begrüßung aus
<3> Ruft die Funktion auf

  • Die Callouts <1>, <2>, <3> verweisen auf Erläuterungen unterhalb des Code-Blocks.

  • Sie ermöglichen eine direkte Verknüpfung zwischen Code und Erklärung.

Callout-Icons anpassen

Die Darstellung der Callout-Zahlen kann über das Attribut :icons: angepasst werden:

:icons: font

  • font nutzt die Standard-Schriftzeichen für Callouts.

  • image ersetzt sie durch kleine Grafiken, wenn entsprechende Bilder vorhanden sind.

Wie im Video erwähnt müssen die Bilder für :icons: image in den Medien in einem eigenen Unterordner "callouts" hinzugefügt werden. Benennen Sie das jeweilige Bild mit der Nummer der jeweiligen Callout-Ziffer und setzen Sie :iconsdir: im Dokumentenkopf.

Back
Next