Hi, A small note about images, and writing style for those... It would be good to keep figures at the bottom of the text. So that they can be easily ignored, or stripped out for any editors/interpreters that don't support showing inline images. Also, keeping as much formatting out of the docs as possible should also be a goal. Since people will have to read unformatted versions too (again when doing things like help(pygame.init)).
cya On Fri, Mar 4, 2011 at 12:18 AM, jug <[email protected]> wrote: > 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 >> >> >> >
