Auschecken des Projekts
$ git clone https://github.com/veit/plone-nutzerhandbuch.git
Wechseln in das Verzeichnis
$ cd plone-nutzerhandbuch
Installation des Sphinx Documentation Generator
$ python3 -m venv .
$ source bin/activate
$ python -m pip install -r docs/requirements.txt
Erstellen der HTML-Dateien in plone-nutzerhandbuch/docs/html/
$ cd docs/
$ make html
Falls Sie die Sourcen für Ihre Zwecke anpassen möchten, beachten Sie bitte, dass Sphinx ein reStructuredText Primer für ReStructuredText bereitstellt.
In collective.developermanual steht auch ein Skript bereit, das mit `collective.transmogrify`_ die generierten HTML-Seiten von Sphinx einfach in eine Plone-Site integriert.
Gerne richten wir für Sie auch einen eigenen Zweig auf unserem Repository ein, sodass Sie das Nutzerhandbuch für Ihre Plone-Site anpassen können und zugleich einfach Änderungen aus dem Hauptzweig des Entwicklerhandbuchs übernehmen können. Schreiben Sie uns hierzu einfach eine E-Mail an plone-nutzerhandbuch@veit-schiele.de
Hier einige Regeln, die bei der Dokumentation beachtet werden sollten:
Die Hauptüberschrift, die auch im Inhaltsverzeichnis erscheint, sollte so geschrieben werden:
======================================
Installation des Plone-Nutzerhandbuchs
======================================
Jedes Kapitel oder jeder Ordner muss eine index.txt
-Datei mit folgenden Abschnitten enthalten:
Überschrift des Abschnitts: Dieser wird im Inhaltsverzeichnis angezeigt.
Sphinx toctree
-Anweisung wobei jede Datei in diesem Ordner verlinkt sein sollte.
Mit Pygments lassen sich Hervorhebungen in Sphinx angeben.
Auch verschiedenartige Hervorhebungen lassen sich realisieren:
für Python-Skripte:
.. code-block:: python
if "foo" == "bar":
pass
Für XML:
.. code-block:: xml
<?xml version="1.0" encoding="UTF-8"?>
<rules
xmlns="http://namespaces.plone.org/xdv"
xmlns:css="http://namespaces.plone.org/xdv+css">
...
</rules>
Für Angaben in der Konsole:
.. code-block:: console
$ sh myscript.sh
Soll ein gesamtes Dokument hervorgehoben werden, kann dies z.B. so geschehen:
..highlight\:\: console
$ ./bin/instance start
Kursiv:
*Italic*
Halbfett:
**Halbfett**
Hervorhebung von Code innerhalb einer Zeile:
``code_hervorhebung``
Externe Links:
`Externer Link <http://www.plone-nutzerhandbuch.de>`_
Interner Link:
:doc:`Interner Link </erweiterungen/poi/aufgabenverwaltung-erstellen.txt>`
Aufzählungsliste:
* Erster Punkt
* Zweiter Punkt
Informationsboxen lassen sich in Sphinx mit den Anweisungen warning
und note
angeben.
Warnung
Diese Box enthält eine Warnung!
Warnungen wie diese können so angegeben werden:
.. warning::
Diese Box enthält eine Warnung!
Bemerkung
Diese Box enthält einen Hinweis!
.. note::
Diese Box enthält einen Hinweis!
Tipp
Diese Box enthält einen Tipp!
.. tip::
Diese Box enthält einen Tipp!
Zu tun
Diese Box enthält ein To-do!
.. todo::
Diese Box enthält ein To-do!