Installation des Plone-Nutzungshandbuchs

  1. Auschecken des Projekts

    $ git clone https://github.com/veit/plone-nutzerhandbuch.git
    
  2. Wechseln in das Verzeichnis

    $ cd plone-nutzerhandbuch
    
  3. Installation des Sphinx Documentation Generator

    $ python3 -m venv .
    $ source bin/activate
    $ python -m pip install -r docs/requirements.txt
    
  4. 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.

Beteiligen Sie sich an der Dokumentation

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

Dokumentenformat

Hier einige Regeln, die bei der Dokumentation beachtet werden sollten:

Seitenstruktur

Die Hauptüberschrift, die auch im Inhaltsverzeichnis erscheint, sollte so geschrieben werden:

======================================
Installation des Plone-Nutzerhandbuchs
======================================

Kapitelstruktur

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.

Hervorhebungen

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
    

RestructuredText-Markierungen

  • 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

Informationsboxen lassen sich in Sphinx mit den Anweisungen warning und note angeben.

Warnungen

Warnung

Diese Box enthält eine Warnung!

Warnungen wie diese können so angegeben werden:

.. warning::

    Diese Box enthält eine Warnung!

Hinweise

Bemerkung

Diese Box enthält einen Hinweis!

.. note::

    Diese Box enthält einen Hinweis!

Tipps

Tipp

Diese Box enthält einen Tipp!

.. tip::
    Diese Box enthält einen Tipp!

ToDo

Zu tun

Diese Box enthält ein To-do!

.. todo::
    Diese Box enthält ein To-do!