[geklärt] Problem mit reStructuredText @ epydoc

[sape]

Hi.

Code: Alles auswählen

::

  Whitespace, newlines, blank lines, and
  all kinds of markup (like *this* or
  \this) is preserved by literal blocks.

Wenn ich das so verwende und dann epidoc benutze wird mir das \ nicht angezeigt. Warum? Ich suche eine Möglichkeiten wie ich mir \, \n anzeigen lassen kann ohne \\, \\n

...

Hab auch ein Problem bei >>>.

Wenn ich z.B.

Code: Alles auswählen

"""
>>> li = ["print 'foobar'", "def \\\n", "foobar\\\n", "():", "    pass"]
"""

gibt es Probleme mit den \\\n.

Line 263: Definition list ends without a blank line: unexpected unident

Stimmt aber nicht die Fehlermeldung

Was soll der mist?

lg

P.S.: Auf ``def \\\\\\n`` statt ``def \\\n`` habe ich keine Bock, weil man die Doku auch mit `help()` lesen und ohne epidoc output verstehen können sollte...

[BlackJack]

Hi.

Code: Alles auswählen

::

  Whitespace, newlines, blank lines, and
  all kinds of markup (like *this* or
  \this) is preserved by literal blocks.

Wenn ich das so verwende und dann epidoc benutze wird mir das \ nicht angezeigt. Warum?

Weil da in der letzten Zeile '\t' am Anfang steht, also ein Tabulator-Zeichen.

Hab auch ein Problem bei >>>.

Wenn ich z.B.

Code: Alles auswählen

"""
>>> li = ["print 'foobar'", "def \\\n", "foobar\\\n", "():", "    pass"]
"""

gibt es Probleme mit den \\\n.

Jo:

Code: Alles auswählen

In [7]: a = """
   ...: >>> li = ["print 'foobar'", "def \\\n", "foobar\\\n", "():", "    pass"]   ...: """

In [8]: print a

>>> li = ["print 'foobar'", "def \
", "foobar\
", "():", "    pass"]

Line 263: Definition list ends without a blank line: unexpected unident

Stimmt aber nicht die Fehlermeldung

Vielleicht stimmt sie doch. Ohne den Quelltext um das nachvollziehen zu können, lässt sich das aber schlecht sagen.

P.S.: Auf ``def \\\\\\n`` statt ``def \\\n`` habe ich keine Bock, weil man die Doku auch mit `help()` lesen und ohne epidoc output verstehen können sollte...

Hast Du Deine Doku mal mit `help()` ausprobiert?

Code: Alles auswählen

In [9]: def f():
   ...:     """
   ...:     >>> li = ["print 'foobar'", "def \\\n", "foobar\\\n", "():", "    pass"]
   ...:     """
   ...:     pass
   ...:

In [10]: help(f)

Help on function f in module __main__:

f()
        >>> li = ["print 'foobar'", "def \
    ", "foobar\
    ", "():", "    pass"]

Das ist nicht das was Du willst oder?

[Joghurt]

Sollte das nicht \\n statt \\\n sein? Letzteres ist ja gerade ein Backslash gefolgt von einem Newline...

[sape]

Weil da in der letzten Zeile '\t' am Anfang steht, also ein Tabulator-Zeichen.

Eben nicht. Mir ist schon klar dass so was interpretiert wird. Ich nutze zum Beispiel in Docstrings auch das \ (genauer -> \\n ohne \n) um Zeilen zu verbinden. Aber :: soll ja gerade das escaping verhindern Hier das Beispiel: http://docutils.sourceforge.net/docs/us ... ral-blocks
Deshalb wundert mich das der ganze Markup Kram wie *foobar* im Beispiel geht aber eben nicht die escapes. Ich denke das ist in epydoc einfach noch nicht implementiert(?).

Hast Du Deine Doku mal mit `help()` ausprobiert?

Ne hatte ich noch nicht. OK, dann weiß ich das es nicht an epydoc liegt sondern an Python, selber.

...

Ich denke, das Thema scheint vorerst geklärt. Ich habe nun mehrer Varianten mit :: probiert und keine Klappt wie in den Specs zu reSTR. Vielleicht wird es in eine neuere Version von epydoc umgesetzt wird.

lg

[BlackJack]

Weil da in der letzten Zeile '\t' am Anfang steht, also ein Tabulator-Zeichen.

Eben nicht. Mir ist schon klar dass so was interpretiert wird. Ich nutze zum Beispiel in Docstrings auch das \ (genauer -> \\n ohne \n) um Zeilen zu verbinden. Aber :: soll ja gerade das escaping verhindern Hier das Beispiel: http://docutils.sourceforge.net/docs/us ... ral-blocks
Deshalb wundert mich das der ganze Markup Kram wie *foobar* im Beispiel geht aber eben nicht die escapes. Ich denke das ist in epydoc einfach noch nicht implementiert(?).

Doch da steht ein Tabulatorzeichen. Das ist eine Python Zeichenkette und keine Textdatei. Wenn Du mit den Beispielen aus der reST-Doku vergleichst, dann musst Du schon die Zeichenketten so schreiben, dass sie mit ``print`` ausgegeben so aussehen wie die Beispiele und nicht im Python-Quelltext.

Ich denke, das Thema scheint vorerst geklärt. Ich habe nun mehrer Varianten mit :: probiert und keine Klappt wie in den Specs zu reSTR. Vielleicht wird es in eine neuere Version von epydoc umgesetzt wird.

Nochmal: Als allererstes musst Du die Regeln berücksichtigen die von literalen Zeichenketten in Python vorgegeben sind.

Code: Alles auswählen

"""
::
  \this
"""

Irgendwie scheinst Du zu erwarten, dass hier das '::' verhindert das '\t' zu einem Tabulatorzeichen wird. '::' hat in Zeichenketten in Python aber absolut keine besondere Bedeutung. Wenn Du dort einen Backslash und ein 't' stehen haben willst, dann musst Du den Backslash schützen.

[sape]

[...]Irgendwie scheinst Du zu erwarten, dass hier das '::' verhindert das '\t' zu einem Tabulatorzeichen wird.
[...]

So hatte ich das Beispiel im Link verstanden

[...]
'::' hat in Zeichenketten in Python aber absolut keine besondere Bedeutung. Wenn Du dort einen Backslash und ein 't' stehen haben willst, dann musst Du den Backslash schützen.

Aber in reSTR leitet das, gefolgt von einer Leerzeile, einen literalen Block ein der doch alle Markups und escapes ausschalten soll. Daher dachte ich das es pydoc schon erkenne würde und das dem entsprechend umsetzt. Aber langsam geht mir da ein Licht auf. Ich glaube Epydoc kann dafür nichts direkt, sondern Python wandelt/Interpretiert die escapes schon beim Parsen, so das Epydoc das nie zu Gesicht bekommt.

[BlackJack]

Aber langsam geht mir da ein Licht auf. Ich glaube Epydoc kann dafür nichts direkt, sondern Python wandelt/Interpretiert die escapes schon beim Parsen, so das Epydoc das nie zu Gesicht bekommt.

Bingo.

Und selbst wenn Epydoc den Quelltext selbst parsen würde, müsste es vorher die Regeln für Escapes in Python-Zeichenketten anwenden, weil die Epydoc-generierte Doku sonst mit der `help()`-Funktion und Doctests inkompatibel wäre.

[sape]

OK, dann hatte ich das falsch verstanden.

Danke & lg
sape

[mitsuhiko]

Ich werfe noch raw strings ein.