Sphinx und Dokumentation von Variablen, Funktionen und Klassen

[pixewakb]

Hallo zusammen, ich bin relativ neu bei Sphinx. Ich bin folgende Dokumentation gewohnt:

Variablen
========

Variable
::Bedeutung der Variable

Funktionen
=========

Funktion
::Aufgabe der Funktion

Klassen
======

Klasse 1
* Eigenschaft
::Bedeutung
* Methode
::Aufgabe der Methode

Gibt es eine einfache Möglichkeit so etwas - automatisiert (!) - in Sphinx zu realisieren? Bislang habe ich nur Klassen und die dortigen öffentlichen Methoden automatisiert dokumentieren können... Auf Hinweise auf state-of-the-art-Projekte wäre ich auch dankbar, wenn ich mir da den Quellcode zum rst-file ansehen kann.

[BlackJack]

@pixewakb: Vollautomatisiert vermutlich nicht falls ”automatisiert” bedeutet das man in Sphinx so gut wie nichts schreibt und alles aus dem Quelltext kommt. Dafür ist Sphinx aber IMHO auch das falsche Werkzeug.

[pixewakb]

Ich hatte mir zunächst epydoc (https://pypi.python.org/pypi/epydoc) angesehen, aber nicht genutzt, weil die aktuell gepflegte Version (lt. Website), zuletzt 2008 aktualisiert wurde. Die Dokumentation, die ich von sphinx erhalte, sieht moderner aus.

Testweise bin ich hiermit weitergekommen:
[codebox=text file=Unbenannt.txt].. automodule:: robot
:members:[/code]

Das dokumentiert eine Klasse, aber nur die Klasse (docstring) und die 'öffentlichen' Methoden.

Meine Frage: Muss ich die Attribute manuell dokumentieren oder gibt es da einen Trick? Für den Rest frage ich ebenso: Mache ich das manuell (z. B. Variablen, Funktionen) oder kann ich das anweisen?

Welche Software nutzt Du zur Dokumentation???

[pixewakb]

Ich komme hier (selbst) weiter: http://www.sphinx-doc.org/en/stable/dom ... ml#domains

@BlackJack Welche Software nutzt Du zur Dokumentation deines Quelltextes???

[DasIch]

Funktions, Klassen und Methoden Definitionen mit Docstrings in eine Textdatei zu kopieren und ein Projekt zu dokumentieren sind unterschiedliche Dinge. Du möchtest ersteres, was nur entfernt mit Dokumentation zu tun hat und Zeitverschwendung ist. Sphinx ist dafür nicht gedacht und du stößt dementsprechend auf Probleme.

Ich würd dir empfehlen dich mit der Folding Funktion deines Editors auseinanderzusetzen, damit kannst du Code auch ausblenden und hast sofort das Ergebnis dass du haben willst.

[pixewakb]

Ich brauche so etwas:

https://docs.python.org/2/library/datetime.html

Da kommt auch Sphinx zum Einsatz, es wäre halt nur schön, wenn die docstrings aus meinem Quelltext direkt in eine Dokumentation umgesetzt werden könnten und ich nicht zweimal die Dokumentation aktuell halten muss. Ich bin neu bei Sphinx - epidoc schien das zu können und zu machen - kann sphinx das nicht???

[BlackJack]

@pixewakb: Das was in der `datetime`-Dokumentation steht möchte man sicher nicht alles im Quelltext stehen haben. Das ist ja auch tatsächlich als Fliesstext geschriebene Dokumentation und nicht nur ein paar lose Docstrings als API-Dokumentation formatiert.

Du musst nicht zwei Varianten parallel aktuell halten. Mittels `autodoc` kannst Du Docstrings aus dem Quelltext in die mit Sphinx erstellte Dokumentation einfügen.

Epydoc ist so etwas wie JavaDoc. Das kann *und will* Sphinx nicht. Wenn's moderner aussehen soll: Es gab da Projekte die ebenfalls wie Epydoc JavaDoc nachgemacht haben, aber die sind anscheinend alle wieder eingeschlafen. Diese Art zu dokumentieren ist einfach, aber oft kommt da eben keine *sinnvolle* Dokumentation heraus die tatsächlich einen Mehrwert bietet, oder der ist irgendwo in dem ganzen autogenerierten Boilerplate versteckt, so dass man ihn erst suchen muss.

Bei Python kommt noch hinzu, dass man ab und zu auch Klassen dokumentieren möchte die es im Code gar nicht gibt, weil auch mal Basisklassen oder ”Interfaces” (a.k.a. Protokolle) dokumentiert werden müssen, die ”physisch” im Quelltext nicht existent sind.

Du könntest, wenn es nur um das Aussehen geht, auch schauen wie man die Templates und das CSS von Epydoc beeinflussen kann.

Ein aktiv entwickeltes Programm wäre noch Doxygen. Das ist zwar nicht primär für Python gedacht, aber AFAIK gibt es dafür mindestens ein Plugin wenn es von sich aus kein Python verarbeiten kann.

[pixewakb]

Es gibt noch pydoc (der Vollständigkeit halber), was macht, was ich möchte, aber leider nicht in der Form, wie ich es gerne hätte.

Ich bleibe wohl erst einmal bei sphinx bzw. meiner MediaWiki-Installation.

[pixewakb]

Ich arbeite mich mit sphinx voran, ich poste das, falls noch mal ähnliche Probleme lösen muss wie ich jetzt.

Ich habe ein Beispielmodul geschrieben, das über Variablen, Funktionen und Klassen verfügt:

Code: Alles auswählen

#: Contains the name of a robot
robot = "Name des Robots"


def get_robotname(robot):
    """ returns the name of a robot"""
    return str(robot)


class Robot(object):
    """This class simulates a robot.

    :ivar name: initial value: name
    :ivar speed: initial value: 0
    """

    def __init__(self, name):
        """ Initiator """
        self.name = name
        self.speed = 0

    def accelerate(self):
        """This speeds up the robot."""
        self.speed += 10
        
    def __str__(self):
        """Returns the name of the robot."""
        return self.name


if __name__ == "__main__":

    robot = Robot("Test")
    

In einem rst-file habe ich nun eingefügt:
[codebox=text file=Unbenannt.txt].. automodule:: robot
:members:
:undoc-members:[/code]

Das liefert mir dann in der Dokumentation grob das, was ich eigentlich haben wollte. Aktuell kann ich automatisch noch nicht die magischen Funktionen dokumentieren, aber das Resultat ist nah an dem, was ich eigentlich brauche/wünsche und hat Potential mir deutlich Arbeit abzunehmen...

Möglicherweise ist es für andere interessant.

[BlackJack]

@pixewakb: Was ist ein „Initiator“?

Ich würde noch mal gerne betonen das Du versuchst Sphinx in einer Weise zu verwenden für die es nicht gedacht ist. Zum Beispiel `get_robotname()` ist so eine furchtbare JavaDoc-artige ”Dokumentation” die absolut sinnbefreit ist. Die enthält 0 Information. Was sollte eine Funktion mit dem Namen und einem `robot`-Argument sonst machen? Ähnlich bei `accelerate()`, wobei es dort Sinn machen könnte wenn man die 10 erwähnt, denn wie stark beschleunigt wird, kann man der Methode nicht ansehen.

Die magischen Methoden dokumentiert man nicht bei den Methoden, denn die werden ja auch nicht aufgerufen. Das ist etwas was zum Datentyp gehört, wo man dann schreibt das es eine Abbildung oder eine Sequenz ist wenn man `__getitem__()`/`__setitem__()` und eventuell `__len__()` und `__iter__()` entsprechend implementiert. Das man ein Objekt in eine Zeichenkette umwandeln kann, würde ich nur in Ausnahmefällen extra erwähnen würde, wenn das tatsächlich Sinn macht.

[pixewakb]

@pixewakb: Was ist ein „Initiator“?

Ich meinte Konstruktor.

Ich würde noch mal gerne betonen das Du versuchst Sphinx in einer Weise zu verwenden für die es nicht gedacht ist. Zum Beispiel `get_robotname()` ist so eine furchtbare JavaDoc-artige ”Dokumentation” die absolut sinnbefreit ist. Die enthält 0 Information. Was sollte eine Funktion mit dem Namen und einem `robot`-Argument sonst machen? Ähnlich bei `accelerate()`, wobei es dort Sinn machen könnte wenn man die 10 erwähnt, denn wie stark beschleunigt wird, kann man der Methode nicht ansehen.

Ich habe das gestern zusammengezimmert, um irgendwie ein Skript mit Variabler, Klasse und Funktion zu haben.

Ich benötige genauso eine Dokumentation. Ich habe es mit Modulen und Bibliotheken zu tun, die ich vielleicht einmal im Jahr verwende und die sonst immer in Skripten verbaut arbeiten, d. h. ich vergesse schnell wie die Sachen implementiert sind und wie ich sie nutzen kann. Möglicherweise sprechen wir aneinander vorbei, aber meine bisherigen Dokumentationen sehen genauso aus, d. h. Funktionsname mit den Parametern und darunter eine Aufgabenbeschreibung. Ich habe in meinen Dokumentationen noch mehr stehen, z. B., worum es geht, was bereitgestellt wird usw. Dafür kann ich dann sphinx auch gut nutzen.

Die magischen Methoden dokumentiert man nicht bei den Methoden, denn die werden ja auch nicht aufgerufen. Das ist etwas was zum Datentyp gehört, wo man dann schreibt das es eine Abbildung oder eine Sequenz ist wenn man `__getitem__()`/`__setitem__()` und eventuell `__len__()` und `__iter__()` entsprechend implementiert. Das man ein Objekt in eine Zeichenkette umwandeln kann, würde ich nur in Ausnahmefällen extra erwähnen würde, wenn das tatsächlich Sinn macht.

Was verstehst Du unter Datentyp?

Wie genau würde bei Dir eine Dokumentation (in groben Zügen) aussehen?

[BlackJack]

@pixewakb: Meine Dokumentationen ”dokumentieren” keine offensichtlichen Sachen. Wenn man aus Funktions- oder Methodenname und den Namen der Argumente ablesen kann was die Funktion/Methode macht, dann braucht man das nicht noch mal als Text hin zu schreiben. Das ist so die typische Java-Dokumentation die viele als sinnlos empfinden. Etwas wie „setName(name) - set the name to `name`“, „getName() - get the name“, oder „frobnicate(foo) - frobnicate a foo“ ist verschwendete Zeit sowohl beim schreiben als auch beim lesen. Bei so etwas dokumentiere ich die Sachen nicht einzeln und alphabetisch, sondern ich versuche Text zu schreiben der die Einzelteile sinnvoll in Abschnitte zusammenfasst und erwähne in den entsprechenden Abschnitten die offensichtlichen Sachen. Also *das* es sie gibt, nicht was sie machen, weil das ja bereits klar ist. Für die alphabetische Auflistung gibt es den Index. Und wenn man Beispielsweise eine Klasse `Parrots` hat, die `__iter__()`, `__getitem__()` und `__len__()` implementiert, dann reicht es zu erwähnen das `Parrots`-Exemplare Sequenzen von `Parrot`-Exemplaren sind.

Datentyp ist ein Wertebereich und Operationen darauf. In Python also das was man mit Klassen beschreibt.