Benutzer-Werkzeuge

Webseiten-Werkzeuge


Übersetzungen dieser Seite:

Sidebar

Hauptmenü

(oSP 12.11-hiccup.8)
 [[dokumentation:sphinx]] 

Linuxmuster.net mit Sphinx und github dokumentieren

Vorbereitung Ticketsystem

  • Bitte beim ticketsystem http://www.linuxmuster.net/flyspray anmelden
  • Ticket zu zugehörigen Problem/Aufgabe suchen und anlegen, falls es keines dazu gibt, so dass man das Ticket selbst übernehmen kann.

Vorbereitung deines Computers (linux)

  • Installiere git
    $ sudo aptitude install git
  • Installiere Sphinx und Latex
    # sudo aptitude -R install python3-sphinx texlive texlive-latex-extra texlive-lang-german

Vorbereitung github

Im weiteren Verlauf werden immer https://-URLs (z.B. https://github.com/linuxmuster-docs/all-of-me.git) verwendet, für die man keinen ssh-Schlüssel braucht. Mit ssh-Schlüssel verwendet man sinnvollerweise immer die entsprechenden github-URLs (entsprechend git@github.com:linuxmuster-docs/all-of-me.git)

  • Fork das Repository „all-of-me“ im github-webinterface (Klicke auf „Fork“ rechts oben)
  • Klone deinen Fork (ersetze mein-github-konto mit deinem github-konto)
    ~$ git clone https://github.com/mein-github-konto/all-of-me.git all-of-me-fork
    ~$ cd all-of-me-fork
  • Deinen Klon so einrichten, dass man ihn mit der offiziellen Dokumentation synchronisieren kann:
    all-of-me-fork$ git remote add upstream https://github.com/linuxmuster-docs/all-of-me.git
    all-of-me-fork$ git remote -v
    origin	https://github.com/mein-github-konto/all-of-me.git (fetch)
    origin	https://github.com/mein-github-konto/all-of-me.git (push)
    upstream	https://github.com/linuxmuster-docs/all-of-me.git (fetch)
    upstream	https://github.com/linuxmuster-docs/all-of-me.git (push)

Erster Test: lokale Dokumentation erstellen

Deinen Klon einfach mal komplieren:

~$ cd all-of-me-fork
~/all-of-me-fork$ make html

Falls der Code (mit wenigen Warnings) erfolgreich kompiliert, kann man das Resultat im Browser anschauen

~/all-of-me-fork$ xdg-open build/html/index.html

Falls der Code nicht kompiliert, sollten erst die Fehler beseitigt werden, bevor man weitermacht.

Bestehende Dokumentation ändern (Pull-Request-Verfahren)

Wenn man jetzt loslegen will, sollte man zuerst die Regeln lesen:

Leitlinien zur Dokumentation in sphinx

  • Übernehme ein entsprechendes Ticket im Ticketsystem
  • Make your changes in your code
  • Commit your changes
    all-of-me-fork$ git commit -a -m"bugfix für ..."
  • Push your changes
    all-of-me-fork$ git push
    Username for 'https://github.com': mein-github-konto
    Password for 'https://mein-github-konto@github.com': 
    Zähle Objekte: 3, Fertig.
    Delta compression using up to 4 threads.
    Komprimiere Objekte: 100% (3/3), Fertig.
    Schreibe Objekte: 100% (3/3), 4within the 95 bytes | 0 bytes/s, Fertig.
    Total 3 (delta 2), reused 0 (delta 0)
    To https://github.com/mein-github-konto/all-of-me.git
       d130eae..da584d5  master -> master
  • Erstelle einen Pull-Request unter https://github.com/mein-github-konto/all-of-me mit dem Knopf „New Pull request“.
  • Ändere das Ticket im Ticket-System auf „Requires testing“
  • Nerve die Dokumentatoren unter dokumentation@linuxmuster.net solange, bis dein Pull-Request angenommen wurde.
  • Sobald er angenommen wurde und immer, wenn du etwas neues beitragen willst, musst du dein Repository wieder auf den neuesten Stand bringen:
    all-of-me-fork$ git fetch upstream
    all-of-me-fork$ git checkout master
    all-of-me-fork$ git merge upstream/master
    all-of-me-fork$ git push
  • Schließe das Ticket im Ticket-System

Übersetzung anpassen

.. todo

Neue Dokumentation beginnen

Neue Dokumente, die noch zu keinem Kapitel in der Dokumentation passen, kann man zunächst in ein eigenes Repository erstellen. Dafür gibt es ein Beispiel-Repository meta-example, das die Build-Umgebung für sphinx bereits enthält.

  • Das meta-example in ein eigenes Verzeichnis (Bsp: „Overheadprojektoren reparieren“) auschecken
    linuxadmin@meinpc:~/linuxmuster.net$ git clone https://github.com/linuxmuster-docs/meta_example.git repair-overheads
    Nach »meta_example« wird geklont
    remote: Counting objects: 102, done.
    remote: Compressing objects: 100% (95/95), done.
    remote: Total 102 (delta 2), reused 99 (delta 2), pack-reused 0
    Objekte werden empfangen: 100% (102/102), 1.09 MiB | 1.19 MiB/s, done.
    Unterschiede werden aufgelöst: 100% (2/2), done.
    Verbundenheit wird überprüft … Fertig.
  • Die Beispiel git-informationen löschen und ein neues git-repository lokal erstellen
    ~/linuxmuster.net$ cd repair-overheads
    ~/linuxmuster.net/repair-overheads$ rm -rf .git
    ~/linuxmuster.net/repair-overheads$ git init
    ~/linuxmuster.net/repair-overheads$ git add .
    ~/linuxmuster.net/repair-overheads$ git commit -a -m"First commit"
  • Ein neues git-Repository auf github erzeugen: https://github.com/linuxmuster-docs → „New Repository“ → „repair-overheads“ (ohne README-Erstellung und .gitignore)
  • Github zeigt einem die weiteren Schritte. Obige „first commits“ wurden bereits erzeugt, daher geht es weiter mit
    $ git remote add origin git@github.com:linuxmuster-docs/repair-overheads.git
    $ git push -u origin master

Wenn man "fertig" ist

Wenn das geschriebene Kapitel gut genug geworden ist, kann man eine E-Mail an uns schreiben und das Repository wird in die Dokumentation eingepflegt. Danach kann man sein repository wieder löschen und alle weitere Dokumentation kann über Pull-requests in die Dokumentation erfolgen.

rST/Sphinx Tipps und Regeln

Regeln lesen:

Leitlinien zur Dokumentation in sphinx

An dieser Stelle könnte man Hilfe zum Markup „rST“ brauchen:

Happy Hacking the doku!

Sphinx kompilieren

  • Optionen zum Übersetzen anzeigen lassen mit make help
    • Erzeugen von HTML: make html → Ergebnis wird erzeugt als ./build/html/index.html
    • Erzeugen von PDF: make latexpdf → Ergebnis wird erzeugt als ./build/latex/<name>.pdf
  • source/conf.py: Konfiguration kann man erstmal lassen, wie es ist.
  • index.rst: Verweist auf Kapitel
  • <kapitelname>.rst: kapitel <name>
  • Bilder im Unterverzeichnis media

Andere Ideen

Umwandeln von .odt zu sphinx

Das Programm odt2sphinx gibt es hier (Beschreibung) https://pypi.python.org/pypi/odt2sphinx/

Installieren von PIL

sudo su
apt-get update
apt-get install python-imaging python-pip python-dev
apt-get install libjpeg8 libjpeg62-dev libfreetype6 libfreetype6-dev
pip install Pillow # Ubuntu 14.04 - aus dem Paketsystem

Installation

easy_install odt2sphinx

  Usage:
    odt2sphinx [options] filename.odt [targetdir]
    odt2sphinx [options] config.cfg
 
  config.cfg content:
    [path/to/the/file.odt]
    targetdir = path/to/the/targetdir
 
  Options:
    -h, --help            show this help message and exit
    --debug
    --download-source-link

z.B.

 odt2sphinx meinedatei,odt /tmp/outdir/

Tips und Tricks

Newline einfügen:

If you add the following to your main .rst file:

.. |br| raw:: html

   <br />

Then in your markup you can add in |br| to create linebreaks just for HTML.

I want to break this line here: |br| after the break.

From: http://docutils.sourceforge.net/FAQ.html#how-to-indicate-a-line-break-or-a-significant-newline
 [[dokumentation:sphinx]] dokumentation/sphinx.txt · Zuletzt geändert: 2016/09/07 14:22 von Tobias