Auschecken des Projekts
$ svn co https://dev.veit-schiele.de/svn/plone-nutzerhandbuch/trunk/ plone-nutzerhandbuch
Wechseln in das Verzeichnis
$ cd plone-nutzerhandbuch
Installation des Sphinx Documentation Generator
$ python2.7 bootstrap.py
$ ./bin/buildout
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 erweitertes Markup 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:
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
TODO: Diese Box enthält einen Hinweis!
.. note::
TODO: Diese Box enthält einen Hinweis!