Re: [pygame] Using reStructuredText for document sources

[Lenard Lindstrom <len-l@xxxxxxxxx>]

Hi Julian,

If the current Pygame layout can be recreated from your reST then 
updating them is a practical. But I am unsure that Python directives 
will do everything we want. If existing directives can be embellished, 
then great. But if the only way to alter an existing directive is to 
derive a new one from it, then the Pygame files will use different 
section names. Also, some fields get moved around. Such cut and past 
rearranging is error prone, not to mention just plain tedious. And if it 
can be done easier with a script, well that is what I am doing. Anyway, 
I already have one advantage you didn't, a working reST translation of 
the Pygame docs on which to model the translator's output. My translator 
already produces reST that compiles with your tool chain. One final 
consideration: the extension module doc strings are generated, as C 
header files, from the doc files. The same must be possible with the 
reST files. They may need extra markup.

As for the Pygame html document layout, I think the first step is to 
recreate the existing format. If docutils and Sphinx are not flexible 
enough to let us then play with the layout, without touching the source 
reST, then the move to reST is questionable. I do like having the 
function or class prototype as a section header; the headers in the 
current html are redundant. Also the menu at the very top of the page 
could be moved to a sidebar. As for the color scheme, style sheets are 
another distutils/xhtml feature I indent to use.

I think the issue with the online documents is that it is from the last 
official Pygame release, which came out over a year ago. Pygame has 
progressed a lot since then. Maybe there needs to be a second, 
frequently updated, version available. As for comments, they can be 
hidden. But some way is needed to flush them. Maybe comments should only 
be allowed for the frequently updated docs, with comments older than 
(let's say) six months automatically deleted.

Lenard Lindstrom

On 03/03/11 04:18 PM, jug 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