Documentation: Just do it.

[David Pineau]

Hi folks !

Since we're planning to move from this obscure codeworker to python,
AND we are planning to document the code as well as the language, we
should take great care about how we go at it.

It is planned to use one of python's documentation frameworks, such as
Sphinx (forgive me if I mispelled it), but I do think that the points
hinted by the following talk's orator are part of the most important
points. If you didn't see the conf, here is the link:
http://pyvideo.org/video/1795/write-the-docs

What are your opinions ?
We may be in a bit of a different domain, as we're writing a compiler
and defining a language, but I feel that part of his advice still
applies to us; and I'd love to have some great documentation for our
(future?) users.

--
David Pineau,
Developer R&D at Scality

[Lionel Auroux]

I'm slightly agree with the speaker's arguments which are the reasons why I choose SPHINX. Unlike doxygen, your focus is on a structured documentation. You only generate some part of this with your code. So we can write first part of a documentation as a "story about ...",some case study and finish with a complete API listing of features/functions...  I want to experiment this method with the writing of pyrser documentation. As I want to use part of my course into it to create a "how to parsing style" documentation with progressive part, examples, etc... For pyrser I already know how to structure my DOC. For rathaxes, this could be a lot of work. We have already writing stuff but we should to refactor all this stuff into an understandable documentation with sphinx.
Another big feature of sphinx, we'll can write some modules called pygment for syntax highlithing for rathaxes langage.

So we could have a one tool "to rule them all" for our different documentation (compiler, langage, etc...).
It's easy to add merge rule like "no doc - no merge" with the structured text files that sphinx needs.

2013/3/21 David Pineau <dav.p...@gmail.com>

--
--
ML Rathaxes
www.rathaxes.org

---
You received this message because you are subscribed to the Google Groups "Rathaxes Development List" group.
To unsubscribe from this group and stop receiving emails from it, send an email to rathaxes-deve...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
Cordialement,
Lionel Auroux

[Louis Opter]

I agree on the tools, sphinx and pygments are very cool (try alias
cat="pygmentize -g" for a moment).

Also with Sphinx you can mix both structured documentation with
documentation inlined in the code.

Here is some projects, other than Sphinx itself, that have very well
written documentation with Sphinx:

- http://flask.pocoo.org/docs/
- http://werkzeug.pocoo.org/
- http://jinja.pocoo.org/

Now, about the video, I couldn't count all the times the speaker said:
"I'm not going to talk about that". I think in the end it's all good
sense.

Louis Opter

[Thomas Sanchez]

I agree on Sphinx too

2013/3/23 Louis Opter <kale...@kalessin.fr>

--
--
ML Rathaxes
www.rathaxes.org

---
You received this message because you are subscribed to the Google Groups "Rathaxes Development List" group.
To unsubscribe from this group and stop receiving emails from it, send an email to rathaxes-deve...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
Thomas Sanchez