Hilfe für Sphinx

[bennnil]

Code: Alles auswählen

C:\Python27\Scripts\Dokumentation\source\index.rst:6: WARNING: undecodable sourc
e characters, replacing with "?": 'Einf>>>\xfc<<<hrung in Sphinx'

Das ist die Warnung.

Was muss ich also in der conf.py angeben, damit er das nicht mehr macht?

eigendlich steht bei mir

Code: Alles auswählen

# -*- coding: utf-8 -*-

drin

[Hyperion]

Speicherst Du die Datei denn auch wirklich in utf-8?

[BlackJack]

@bennnil: Und wo steht der Kommentar? In der `conf.py`? Dann gilt der für diese Datei und dort auch nur für Unicode-Literale, also Zeichenketten mit einem u davor wie zum Beispiel u'Hällö' und natürlich muss die Datei dann auch tatsächlich UTF-8-kodiert gespeichert werden.

Es sieht so aus, als wenn die `index.rst` nicht UTF-8 kodiert gespeichert ist, denn da ist ja nur ein Byte für das ü in Einführung zu sehen.

[bennnil]

Mein Fehler war es in ASCII abzuspeichern :/ Wie dumm aber danke für die Tipps
Hier ist noch ein Problem:

Code: Alles auswählen

Installation von Sphinx
-----------------------
Die einfachste Installation von Sphinx läuft über **EasyInstall**, da alle benötigten Versionen direkt heruntergeladen werden.

#. EasyInstall aus dem Internet herunterladen (\`<http://www.python.org/download/releases/>`_)\ (auf richtige Version achten)
#. Ins vorgeschlagene Verzeichnis installieren.
#. *easy_install –U* Sphinx in die Kommandozeile eintippen.
#. Umgebungsvariable *C:\\Python27\\Scripts;* setzen.

edit: Easyinstall ist nun EasyInstall
Ich möchte bitte diesen klamauk mit `<>` nicht angezeigt bekommen. Wie geht das?

[Hyperion]

Das Tool heißt 'Easy Install' oder 'EasyInstall'

[lunar]

@bennnil: Für Kommandos sollte man auch besser `` statt * nutzen (also ``easy_install -U Sphinx`` statt *easy_install -U*).

Edit: Falsche Antwort entfernt, hatte mich verlesen

[BlackJack]

@bennnil: Wenn Du die reST-Syntax nicht im erzeugten Dokument haben möchtest, solltest Du sie nicht mit '\' davor ”schützen” als reST-Syntax interpretiert zu werden. Im Falle so einer kompletten URL kannst Du die Auszeichnung aber auch ganz weglassen, denn http://… sollte automatisch erkannt und entsprechend als Link gesetzt werden.

Edit: Ergänzend zu Lunar: Sphinx kennt spezielle Auszeichnungen für so einige Sachen die in technischen, computer-bezogenen Dokumentationen vorkommen können, unter anderem auch für Kommandozeileneingaben, Programmnamen, Beispieleingaben, und so weiter. Siehe Inline Markup.

[bennnil]

Danke für die Tipps ich dachte iwo gelesen zu haben das ich die () Klammern iwie durch \ vom parser ignorieren lassen muss ... aber kann auch iwas anderes gewesen sein

Jetzt funkt es auf jeden Fall... was mich zu meiner nächsten Frage bringt

Ich möchte gerne die offizielle Dokumentation von Sphinx verlinken. Das Optimum wäre, dass die Datei eingebunden wird und ggf. bei Internet die Internetseite von der Doku geöffnet wird. Gibt es da ne Möglichkeit? Sollte das nicht funktionieren, wäre es klasse, wenn ihr mir nur sagen könntet, wie ich die Dokumentation verlinke ... iwie bekomme ich das nicht hin ... muss ich da zuerst ein html Dokument draus erstellen oder wie geht das ?!

Wäre euch sehr dankbar für eure Hilfe

[Hyperion]

Meinst Du diese Seite? Wenn ja musst Du die doch nur als Hyperlink referenzieren... ansonsten kapiere ich Deine Frage nicht!

[bennnil]

Ja das weiß ich wie das geht aber wie geht das, wenn ich die HTML Datei habe und sie lokal auf meinem PC liegt. Muss die dann in .static gepackt werden? Und wie kann ich auf die Datei verweisen ?

Gibt es da relative Pfadangaben? Weil im Besten Fall soll das auf verschiedenen Pcs laufen.

[Hyperion]

Ach so, dann schreib das doch auch in Deine Frage rein!

Probiere doch mal eine relative Pfadangabe - das geht sicherlich schneller, als hier zu fragen

[bennnil]

Ich müsste das können um es zu machen ... ich habe keine Ahnung wie man das macht ... hatte das mal in Informatik in der Schule ... allerdings haben wir das Programme in Delfi zusammengeklickt ...

[Hyperion]

Ich müsste das können um es zu machen ... ich habe keine Ahnung wie man das macht ... hatte das mal in Informatik in der Schule ... allerdings haben wir das Programme in Delfi zusammengeklickt ...

Hä? Den Zusammenhang kapiere ich jetzt nicht. Hier steht doch, wie man Links angibt. Probiere das doch einfach mit dem relativen Pfad aus. Anstelle von `http://www....` schreibst Du da eben nur eine relative Angabe hin. Wo liegt das das Problem?

[bennnil]

okay wie auch immer ... also ich habe es hinbekommen ... ich wusste nicht, dass die / \ sich im Browser und Dateiexplorer unterscheiden darum kam da nur Mist bei raus

Okay ...aber eilich ist mein Problem noch nicht gelöst

Es gibt doch z.b. bei HTML die Möglichkeit, wenn ein Bild oder iein anderer Inhalt nicht geladen werden kann da sonen alternativen Text hinzupacken.

Und ich möchte eben gerne das so haben:

Wenn Internetzugang da ist, soll bitte die Internetseite mit der Doku aufgerufen werden.
Ansonsten soll die lokal abgespeicherte Datei aufgerufen werden.

ich hoffe das ist verständlich

Lg bennnil

[/me]

Es gibt doch z.b. bei HTML die Möglichkeit, wenn ein Bild oder iein anderer Inhalt nicht geladen werden kann da sonen alternativen Text hinzupacken.

Und ich möchte eben gerne das so haben:
Wenn Internetzugang da ist, soll bitte die Internetseite mit der Doku aufgerufen werden.
Ansonsten soll die lokal abgespeicherte Datei aufgerufen werden.

Man kann z.B. bei Bildern ein alt-Attribut angeben um einen Alternativtext anzuzeigen. Komplexere Sachen wie das automatische Umschreiben eines Links sind mit HTML nicht möglich. Vielleicht kann man mit JavaScript da etwas zurechtfummeln.

[bennnil]

und wie realisiere ich das mit Sphinx? ... Das soll in einem Repository enden und das wäre cooler wenn da nur die rst datei wäre die dann mit ner batch konvertiert wird und nicht schon die fertige HTML datei in der man noch rumpfuschen könnte ...

[bennnil]

Ich habe (schonwieder) eine Frage:

Auch wenn das hier ein Python Forum ist, würde ich gerne wissen, ob jemand schonmal mit Sphinx ein C Programm dokumentiert hat.

Wie müsste ich zum Beispiel das folgende Projekt Dokumentieren?

Code: Alles auswählen

#include<stdio.h>
 
int main()
{
   printf("Hello World\n");
   return 0;
}

Außerdem habe ich noch nicht ganz verstanden, wie man index.rst mit den Programmdateien bzw. genauergesagt mit den Kommentaren in der Programmdatei verknüpft.
Angenommen ich bekomme ein fertigen Softwarequellcode und soll nun eine Dokumentation davon erstellen. Was müsste ich (vorausgesetzt ich würde verstehen was die Funktionen usw. machen) tun, damit ich daraus eine Dokumentation erstellen kann ?

Danke

[lunar]

@bennnil: Im Bezug auf C kannst Du Sphinx-Dokumentation gar nicht mit den Kommentaren in den Quelltext-Dateien „verknüpfen“. Du musst jede C-Funktion manuell in einer RST-Datei dokumentieren, im Bezug auf "main" beispielsweise mit:

Code: Alles auswählen

.. c:function:: int main()

   Program entry point. 

   Returns the exit code.

Steht aber alles auch in der Sphinx-Dokumentation …

[bennnil]

Also anscheinend verstehe ich das immernoch nicht. :K Hättet ihr mal nen Link wo ein Programm dokumentiert ist und wo das am besten auch schon in der entsprechenden Ordnerstruktur ist?

ich weiß im Moment nicht wie ich die Ordner anlegen muss was wo sein muss.

Konkret:
1. Wie sieht beispielsweise ein dokumentiertes Python Projekt aus. (Am besten nicht ein ganz so komplexes)
2. Wie müssen die Sourcecode Dateien und die Index.rst ... organisiert werden?
3. Bringt mir dann die Dokumentation von C Programmen mit Sphinx überhaupt irgendetwas? Schließlich muss ich dann ja praktisch neben der Bemerkungen im Quellcode auchnoch eine zusätzliche Datei erstellen, wo ich das mit reST formatiertem Text beschreibe (--> zusätzliche Arbeit)
4. Wie sieht es mit der Erweiterung breathe aus? (https://github.com/michaeljones/breathe#readme) Ließt die das aus und fügt es zu der Doku hinzu (über XML)
5. Stimmt es, dass Docstrings nur mit Python funktioniert?

Wäre nett, wenn Ihr mir nochmal helfen könntet

[BlackJack]

@bennnil:

1. Auf der Sphinx-Webseite gibt es doch eine reiche Auswahl an Links zu Projekten die Sphinx verwenden: http://sphinx.pocoo.org/examples.html

3. Wenn Du die Dokumentation schon in den Quelltextdateien stehen hast, dann macht Sphinx natürlich mehr Arbeit. Man muss die Dokumentation ja aber nicht in den Quelltext schreiben, sondern kann sie auch ausschliesslich mit Sphinx machen.

4. Die Erweiterung liest nicht selbst aus sondern bindet Doxygen's XML-Ausgabe in Sphinx-Dokumente ein.

5. Die Frage verstehe ich nicht so ganz!?