Hilfe für Sphinx

[bennnil]

Ich danke euch nochmal für eure ganzen Bemühungen. Ich bin gerade dabei die Dokumentation von Sphinx durchzuarbeiten. Dabei wird immer das Wort directive benutzt.
Ich verstehe allerdings nicht was das für eine Bedeutung hat. Ein Beispiel:

Since reST does not have facilities to interconnect several documents, or split documents into multiple output files,
Sphinx uses a custom directive to add relations between the single files the documentation is made of, as well as
tables of contents. The toctree directive is the central element.

Leo.org hilft mir nicht wirklich, da alle Bedeutungen iwie nicht in den Kontext passen. Vielleicht könntet ihr mir nochmal helfen und mir erklären was die damit sagen wollen ...
Ich wäre euch sehr dankbar

[Hyperion]

Also ich finde die Bedeutungen passen: dict.cc

"Anweisung" passt doch ganz gut. Im Gegensatz zur Syntax (also Einrückungen usw.) spielt hier das Wort die zentrale Rolle. Stößt der Sphinx-Parser über so eine "Direktive", so interpretiert er sie und führt entsprechende Logik aus.

[bennnil]

Also wenn das Anweisung heißt (was ich auch zuerst dachte), was möchte mir dann der folgende Absatz mitteilen :K ?

.. toctree::
This directive inserts a "TOC tree" at the current location, using the individual TOCs (including "sub-TOC trees") of
the documents given in the directive body (whose path is relative to the document the directive occurs in).

TOC also Table of Content ist mit Inhaltsverzeichnis zu übersetzen oder ist das etwas besonderes da?

[DasIch]

Eine `directive` ist eine Anweisung an den Parser irgendetwas in spezieller Weise zu formatieren. Diese Anweisungen haben die Syntax

Code: Alles auswählen

.. <name>::
   :option: [argument]\n*

   [body]

Bei der toctree directive wird der Parser Angewiesen einen TOC zu erzeugen, der zu den im Body angegeben Dokumenten verlinkt.

Am besten wäre es wenn du dir mal die Dokumentation von existierenden Projekten als Beispiel anschaust.

[noisefloor]

Hallo,

@bennnil: Das Thema gibt es öfters - ohne Englisch kommt man bei Python (genau so wie bei den meisten anderen Programmiersprachen) nicht weit. Zumindest lesen & verstehen sollte man schon halbwegs gut. Die allerwenigsten Projekte sind in deutsch dokumentiert. Selbst die nicht, die aus dem deutschsprachigen Raum (wie z.B. Sphinx) kommen.

Gruß, noisefloor

[bennnil]

Hallo alle miteinander
Erstmal danke für die Übersetzung
Dann: Es ist nicht so das ich überhaupt kein Englisch spreche. Ich habe dieses Jahr mein Abitur geschrieben und hatte einen Englisch Leistungskurs. Dabei habe ich auch nicht wirklich schlecht abgeschnitten. Das Problem sind auch eher die "Fachbegriffe" in dem Dokument. Daher entschuldigt bitte, wenn ich nachfrage. Es ist eben nicht so einfach das zu übersetzen und dann aufzuschreiben. Denken kann ich mir das u.U. auch, aber ich muss eben sicher sein, damit ich das niederschreiben kann.

[noisefloor]

Hallo,

> Das Problem sind auch eher die "Fachbegriffe" in dem Dokument.
Axo. Dann solltest du kein Problem haben. Das mit den Fachbegriffen und Abkürzungen kriegt man relativ schnell raus, wenn man erst mal ein paar Dokus gelesen hat.

Gruß, noisefloor

[Boa]

Ich schließe mich DasIch an. Um Dokumente in Sphinx zu entwerfen braucht man keine Kenntnisse in Python. Ich selbst habe Sphinx verwendet um meine Protokolle zu schreiben (Protokoll im Sinne von Mitschrift einer Sitzung). Das hat den Praktischen Nutzen, dass ich aus der Dokumentation automatisch Latex, HTML, PDF Dokumente generieren kann. Zudem kann man die Unterschiede zwischen den einzelnen Dokumenten sehr einfach erkennen im Gegesatz zu einer XML Dokumentation muss man sich dabei nicht mit Tags herumschlagen.
Abgesehen davon kann man auch andere Programmiersprachen mit Sphinx dokumentieren:

it has excellent facilities for the documentation of Python projects, but C/C++ is already supported as well, and it is planned to add special support for other languages as well

@bennnil:
Schau dir zusätzlich zu:
http://sphinx.pocoo.org/tutorial.html
Mal folgendes an:
http://packages.python.org/an_example_p ... phinx.html
Da werden übersichtlich Beispiele zu Listen und anderen Formatierungen gezeigt.

Damit solltest du dein erstes Sphinx Dokument erstellen können. Dann hast du schon Mal was zum vorzeigen.
Die Paragraphen die sich um Python Dokumentation kümmern kannst du erst Mal überspringen.
Da du im Softwaredevelopment Bereich arbeitest solltest du dir diese anschließend trotzdem zu Gemüte führen. Das sind sowieso nur Sinnlos Funktionen, die kaum aus Code bestehen und nur veranschaulichen wie man allgemein Methoden/Funktionen definiert.

Ich verwende außerdem ein Skript welches automatisch alle Kommentare aus einem Python Verzeichnis extrahiert und mithilfe von Sphinx die entsprechende Dokumentation generiert. Ich glaube aber, dass das von Sphinx noch nicht direkt unterstützt wird.

[bennnil]

Danke für die Seiten Boa. Auf die bin ich während meiner Recherche auch schon gestoßen. Habe mir jetzt einige Tutorials über Python angeschaut. Da wird das ganze dann schon etwas klarer.

Eine Frage hätte ich noch: Gibt es ein aktuelles PDF Dokument zum ausdrucken, mit der Dokumentation? ... Das vom Januar letzten Jahres habe ich gefunden aber ich weiß nicht wieviel sich von version 0.6.4 bis 1.0.7 geändert hat.

Hat da irgendwer zufällig eine Idee?
Danke im Vorraus

[cofi]

Das vom Juli letzten Jahres steht genau davor und befasst sich mit Version 1.0: http://sphinx.pocoo.org/sphinx.pdf
Wenn dir das nicht reicht, kannst du dir die PDFs selbst generieren, schliesslich ist sphinx mit sphinx dokumentiert.
Den Code gibts hier: https://bitbucket.org/birkenfeld/sphinx/src

[bennnil]

Lieber cofi,
vielen Dank für die Links.
Ich würde am liebsten die aktuellste Version haben . Allerdings bekomme ich das nicht so ganz hin, daraus eine LaTeX Datei zu erzeugen, geschweige denn eine PDF Datei. Zum Ausdrucken wäre das allerdings etwas besser. Die HTML Datei zu erzeugen ist kein Problem. Meine Frage ist also: Bin ich dafür zu blöd, kann man nicht einfach aus den bereitgestellten Daten ein PDF erstellen, oder liegt das Problem tatsächlich bei dem Programm?
Es wäre Klasse, wenn ihr mir nochmal helfen könntet

[BlackJack]

@bennnil: Wo liegt denn das Problem genau? Was für Fehlermeldungen bekommst Du? Welche LaTeX-Distribution verwendest Du?

[cofi]

Unter Linux/Unixen:

Code: Alles auswählen

cd sphinx/doc
make latex
cd _build/latex
make all-pdf

Hier ist das fertige PDF: https://dl.dropbox.com/s/lfmij5c53pj65l ... x.pdf?dl=1

[bennnil]

Da fragst du mich Sachen
ich starte per make latex Befehl in der Kommandozeile. Dann kommt erst ne Menge Text und dann die folgende Fehlermeldung:
Exception occurred:
File "C:\Python27\lib\site-packages\sphinx-1.0.7-py2.7.egg\sphinx\writers\late
x.py", line 1024, in visit_target
next = node.parent.parent[node.parent.parent.index(node.parent)]
AttributeError: 'NoneType' object has no attribute 'index'

Ich habe keine Ahnung was ich falsch mache

Danke für deine Hilfe

[bennnil]

Hey ich habe gerade in der Dokumentation gelesen, dass Sphinx nativ verschiedene Sprachen unterstützt. Wäre es schwierig die Dokumentation, die cofi mir geschickt hat nochmal mit dem Parameter de zu erstellen (also auf deutsch zu übersetzen)?
Oder bringt das nicht viel, da da nur Kauderwelsch rauskäme ?

Bevor ich es vergesse: Allerherzlichsten Dank cofi für deine schnelle Unterstützung. Arbeite (leider) auf einer Windows Maschiene :/

[BlackJack]

@bennnil: Das verschiedene Sprachen unterstützt werden bedeutet nicht, dass Sphinx englische Dokumentation, lesen, verstehen, und dann in andere Sprachen übersetzen kann. Das bezieht sich auf die generierten Texte wie „Inhalt” statt „Content” oder „weiter”/„zurück” statt „next”/„previous”.

[cofi]

Da kommt keine deutsche Dokumentation raus. Es werden nur die Sphinx Texte auf Deutsch, statt auf Englisch ausgegeben. In der HTML Dokumentation ist das zum Beispiel "weiter" oder "Nächstes Thema", nichts weltbewegendes.

Aber damit du weisst wies geht: In der conf.py ein `language = "de"` hinzufuegen.

Edit: Zu langsam

[bennnil]

Achso okay danke euch Beiden für die wirklich schnelle Antwort

[bennnil]

Ich hätte nochmal eine Frage:
Wie kann ich Sphinx dazu bringen Umlaute und ß auszugeben und nicht immer mit ner Warnung und dann nem ? zu reagieren ?

Danke

[BlackJack]

@bennnil: Wie lautet denn die Warnung und mit welcher Kodierung werden die Eingabetexte gespeichert?

Edit: Sollte das etwas anderes als UTF-8 sein, musst Du das in der Konfiguration angeben. Oder besser: die Eingabetexte als UTF-8 speichern.