Re: [pygame] Using reStructuredText for document sources

[jug <jug@xxxxxxxxxxxxxx>]

Hi Lenard,

when I wrote my convert script [1] I reached a point when I found it 
easier to edit the output (rst files) manually instead of implementing 
proper handling for all the special cases etc. So maybe it would be 
better to take my rst-files and continue to improve them (fix last 
markup fix and improve content) as the convert script would be only used 
this single time. Then you can replace the .doc files in the source with 
the rst-files and some sphinx project files for building etc. in a doc 
or ref folder.
To the structure: I think the basic structure (module -> classes -> 
methods) is standard. But the way of documenting stuff could be really 
improved with the features of rst markup (and maybe sphinx 
plug-ins/extensions or however they call it). For example, 
"hugoruscitti" added images to the docs of the transform module. I like 
it a lot as it shows instantly what each single method does and also 
makes the page easier to read as it breaks this big text-only block. The 
template/style for the html-generator could be edited to fit into the 
pygame.org webpage (if not the other way round :-) ). The comments 
feature of the current solution is quite useful, but the result is that 
the comments are not merged into the main documentation and so an 
offline version of the docs is more or less useless (at least for some 
modules or functions). So removing the comment feature would remove 
spam, very long and hence wrong placed example programs and stupid 
"hello world/this is cool/..." dummy comments from the docs. If someone 
has a serious interest to improve the docs somewhere it should not be 
too hard to post a new version (or just a note that a certain part 
should be improved) on the mailing list.

In general, I'm absolutely convinced that a migragion of the pygame 
documentation to a rst/sphinx based system would be an huge improvement 
for pygame. It would be a lot easier for more people to participate in 
writing and improving documentation. The markup would be standardized 
(well, kind of) and the output would be flexible (you can generate 
documentation as webpage, pdf, etc.)

To use a wiki could be better than the current solution, but you'd need 
to moderate it, remove spam/stupid and/or wrong content/etc. -> work, no 
one has time for.

Regards,
Julian

[1] 
https://bitbucket.org/schlangen/pygame-docs/src/00217ff414bb/scripts/make_new_ref.py

Am 04.03.2011 00:09, schrieb Lenard Lindstrom:
> Hi everyone,
>
> It seems that as useful as it has been makeref,py, the custom Pygame 
> document generator, is showing its age. It makes little sense to 
> continue maintaining makeref.py when other, more powerful, document 
> generators are available off-the-shelf. So I am proposing to convert 
> Pygame's custom .doc files to reSTructuredText, and have docutils and 
> Sphinx generate the documents. As well as being the tool chain used to 
> produce the Python documents, Marcus uses reST for pgreloaded. Also, 
> Julian (jug) has translated the Pygame doc source to reST once 
> already. But I admit I did not fully appreciated his efforts at the time.
>
> I am already improving the makeref.py tokenizer for use in a Pygame 
> DOC to reST translator. Julian already wrote a makeref.py based 
> translator. I hope to using his reST version of the Pygame doc sources 
> as a guide for a translator that produces reST files closer to the 
> final product. If nothing else, makeref.py will generate somewhat 
> cleaner web pages.
>
> Before going any further I need to know what to keep from the current 
> Pygame document layout, what should change, and what can be added. I 
> suppose this has been discussed before, but I kind of missed it. Also, 
> if there are objections to moving to reST now is the time to raise them.
>
> Lenard Lindstrom