ReSt beim Package Index...

[jens]

Jemand eine Idee, was an dem RestructuredText bei http://pypi.python.org/pypi/django-reversion-compare/ falsch ist?

gerendert sollte es so aussehen wie bei https://github.com/jedie/django-reversi ... on-compare

[BlackJack]

@jens: Du hast doch sicher mal probiert das selbst zu übersetzen‽ Ich bekomme das hier:

Code: Alles auswählen

$ rst2html.py test.rst > test.html
test.rst:102: (ERROR/3) Document or section may not begin with a transition.

[jens]

indirekt schon.

Denn ich nutzte python-creole dazu, siehe: https://code.google.com/p/python-creole/wiki/UseInSetup denn eigentlich ist die README in creole geschrieben.

Dabei wird bei "register", "sdist", "bdist", "upload", "--long-description" automatisch der erzeugte ReSt code mit rest2html() getestet:
https://github.com/jedie/python-creole/ ... ls.py#L117

Aber du hast recht:

Code: Alles auswählen

$ ./setup.py --long-description > rest2html
<string>:102: (ERROR/3) Document or section may not begin with a transition.

Was bedeutet der Fehler?

EDIT: Also der Fehler kommt auch beim automatisch test. Aber er wird schlicht auf stderr ausgegeben und das war es. Also mehr oder weniger ignoriert
versuche gerade dem publish_parts() bei zu bringen, das er einen echten Fehler werfen soll, mit: settings_overrides={"Traceback": True} und enable_exit_status=1 Passieren tut aber nix...

[BlackJack]

@jens: Der Bedeutet, dass ein Dokument oder ein Abschnitt nicht mit einem Übergang anfangen darf.

Suchspiel: Was ist hier die „transition”, also Zeile 102:

Code: Alles auswählen

-----------
screenshots
-----------

----

How to select the versions to compare:

|django-reversion-compare_v0_1_0-01.png|

[jens]

Danke, das war es...

Ich denke mit https://github.com/jedie/python-creole/ ... 7f365b2a78 sollte es nun auch einen Fehler geben, wenn der "rest2html selbst test" nicht sauber durchläuft... Muß ich aber noch in der Praxis testen...

Anmerkungen dazu?

[lunar]

@jens: Ich kann mich des Eindrucks nicht erwehren, dass Du Dir Deine eigenen Probleme schaffst. Nutze doch einfach ReST, und erspare Dir die aufwendige, und offensichtlich fehlerbehaftete Konvertierung. ReST ist auch nicht komplizierter, und in der Python-Community eigentlich Standard, während Creole eigentlich nur auf Wikipedia funktioniert.

[jens]

Wikipedia nutzt Creole? Ich glaube es ist nur ähnlich...

Also ehrlich mag ich ReSt überhaupt nicht. Ist mir viel zu kompliziert und schlecht dokumentiert. Offensichtlich ist es auch für wesentlich mehr gemacht als simples Markup... Also irgendwie genau das gegenteil von Creole...

Ganz unrecht hat du allerdings nicht, das so manche Fehler nicht wären...

[Leonidas]

Wikipedia nutzt Creole? Ich glaube es ist nur ähnlich...

Glaube ich auch nicht. Ich denke effektiv nutzt niemand Creole. In Python wird ReST verwendet, daneben noch Markdown und das wars.

[lunar]

@jens: Nun gut, dann nutzt halt niemand Creole. Noch ein Grund mehr, eine Alternative zu nutzen…

ReST nicht zu mögen, ist eine Haltung, die sich ein Python-Entwicklung schon wegen Sphinx nicht leisten kann. In der Dokumentation von Sphinx findest Du im Übrigen auch eine umfangreiche Einführung in Rest mit Verweis auf die offizielle Referenzdokumention.

Ich verstehe auch nicht, warum Du ReST für kompliziert hältst. Einfaches Markup ist in ReST auch nicht komplizierter als in Creole, und komplizierte Dinge wie Direktiven oder Ersetzungen musst Du ja in einer README-Datei nicht nutzen, in Creole hast Du diese Dinge ja bisher auch nicht vermisst.

Nutze ReST, oder höre auf mit Python. Alles andere bringt nur Probleme mit sich…

[jens]

Gibt ja nicht wirklich zwingend einen Grund Sphinx zu nutzten, auch wenn es ein schönes Tool zu seinen scheint.

Meine Ablehnung kommt u.a. daher, das es keine wirklich gute ReSt Dokumentation gibt. Zu Creole brauchst du quasi nur das:

...und das ist fast alles was ich brauche.

Meinst du: http://matplotlib.sourceforge.net/sampl ... sheet.html ? Ist schon ganz gut, aber auch nicht so ganz einfach...

Naja, ich hab mich ja durchgeschlagen, ansonsten gäbe es kein html2rest Konverter. Den habe ich eigentlich auch nur aus dem Zwang heraus gemacht, weil PyPi nur ReSt akzeptiert...

Neben der IMHO schlechten Doku, mag ich ReSt halt auch nicht, weil es einfach super aufwendig ist. z.B. wie man Links und Bilder einbindet...

[anogayales]

Nutze ReST, oder höre auf mit Python. Alles andere bringt nur Probleme mit sich…

Nur weil einem _eine_ Möglichkeit nicht gefällt in python Dokumentation zu schreiben, sollte man nicht die Sprache aufgeben.

[lunar]

@jens: Nochmals der Hinweis auf die Rest-Einführung in der Sphinx-Dokumentation, und zudem auf die kompakte Referenz in der docutils-Dokumentation. Damit kannst Du Dir eine ähnliche Tabelle zusammen stellen, oder das bisschen an Syntax, was diese Tabelle aufführt, auch einfach auswendig lernen

Ich möchte Dir Creole nicht schlecht reden, doch ich verstehe ehrlich gesagt nicht, wie man so viel Aufwand treiben kann, nur um "[[http://example.com|Foo bar]]"
statt "`foo bar <http://example.com>`_" schreiben zu können, oder "{{image.png|title}}" statt ".. image:: image.png" oder (für Abbildungen mit Beschriftung):

Code: Alles auswählen

.. figure:: image.png

   Eine lustige Beschreibung

Zumal Creole innerhalb der Python-Community auch so gut wie keine Nutzerbasis hat.

@anogayales: Wenn Rest wirklich nur eine Möglichkeit zur Dokumentation ist, was sind den dann die Alternativen? Insbesondere Alternativen, bei denen man nicht auch mit Rest konfrontiert wird? Ich kenne keine.

[jens]

Ich möchte Dir Creole nicht schlecht reden, doch ich verstehe ehrlich gesagt nicht, wie man so viel Aufwand treiben kann, nur um "[[http://example.com|Foo bar]]"
statt "`foo bar <http://example.com>`_" schreiben zu können, oder "{{image.png|title}}" statt ".. image:: image.png" oder (für Abbildungen mit Beschriftung):

Code: Alles auswählen

.. figure:: image.png

   Eine lustige Beschreibung

Diese Beispiele zeigen es doch gut, wie einfach creole ist und wie umständlich ReSt...

[DasIch]

Diese Beispiele zeigen bestenfalls das ReST eine konsistente Syntax hat die Creole völlig fehlt. Abgesehen davon musst du ReST sowieso nutzen wenn du ein ernsthaftes Projekt und damit auch Dokumentation brauchst, den da bleibt dir nur Sphinx.

[lunar]

@jens: Wenn Du das so siehst, dann haben wir wohl unterschiedliche Vorstellungen vom Begriff "umständlich". Ich sehe da nur, dass man bei ReST ein paar Zeichen mehr schreiben muss, nichts, was mich dazu bewegen würde, mit der Entwicklung eines Konverters zu beginnen. Zumal Du, wie DasIch festgestellt hast, als Python-Entwickler ohnehin früher oder später mit Rest konfrontiert wirst...

Ist natürlich Deine Sache, aber auf Dauer hast Du weniger Probleme, wenn Du Dich einfach an die Toolchain einer Sprache hältst, anstatt gegen sie zu arbeiten... und Rest gehört halt, sowohl durch den Cheeseshop als auch durch Sphinx, fest zu dieser Toolchain.