2.1. Sphinx elementen#

Een Jupyter Book bestaat uit Jupyter Notebooks en Markdown (MyST) bestanden. In beide kun je Sphinx elementen gebruiken (in de MyST Markdown notatie). Deze pagina bevat enkele voorbeelden van Sphinx-elementen.

Sphinx wordt veel gebruikt voor Python-gerelateerde documentatie, zoals je die vindt op https://readthedocs.io.

2.1.1. Admonitions#

Voor waarschuwingen, tips, e.d. zijn er speciale “admonition” blokken, met een gekleurde rand en titel. Voor elk soort betekenis is er een speciale kleur en icon.

Voorbeelden:

Notitie

Dit is een opmerking. Door de vormgeving krijgt deze extra aandacht.

Waarschuwing

Dit is een waarschuwing.

Tip

Dit is een tip.

Deze admonition-blokken worden ook gebruikt voor opdrachten en toetsvragen.

2.1.2. Sphinx design: cards#

Card header 1

Card title 1

Card body 1

Card footer 1

Card header 2

Card title 2

Card body 2

Card footer 2

2.1.3. Aantekeningen in de marge#

Marginal note

Dit is een aantekening in de marge. Deze illustreert de tekst hiernaast.

Een bekende stijl voor (les)boeken is het gebruik van aantekeningen in de marge (marginal notes). Deze stijl wordt onder meer gebruikt in Feynmann’s Lectures on Physics. Edward Tufte maakt hiervan ook graag gebruik.

Dit is één van de stijlen die door Jupyter Book direct ondersteund wordt. Zie: https://jupyterbook.org/content/layout.html

2.1.4. Zijbalk-elementen#

Verbanden zijn belangrijk

Voor het onthouden en verwerken van nieuwe concepten zijn verbanden met andere concepten die je al eerder gezien hebt van belang. In een zijbalk (sidebar) kun je dergelijke verbanden aangeven zonder de lijn van het lopende verhaal te onderbreken.

Je kunt daarvoor aantekeningen in de marge gebruiken, of een zijbalk, zoals hier.

Een ander veel gebruikt element is de zijbalk: een toelichting of voorbeeld bij de lopende tekst, niet direct van belang voor het volgen van de lijn van het verhaal. Je kunt hier bijvoorbeeld een verband met een ander onderwerp aangeven.

In het algemeen is een zijbalk groter en opvallender. Deze trekt soms meer aandacht dan de lopende tekst.