Re: [pygame] updating the docs

[Peter Shinners <pete@xxxxxxxxxxxx>]

> > If it's going to be a "tagged" format, I'd suggest
> > using tags like
> > <method> ... </method>  <class>...</class> ..
> > <function> .. </function>
> 
> I suggest DocBook:
>   <RefEntry>
>     <RefMeta>
>       <RefEntryTitle>surfarray</RefEntryTitle>
>     </RefMeta>
>     <RefNameDiv>
>       <RefName>pygame.surfarray</RefName>
>       <RefPurpose>like a <class>Surface</class>,
>                   but faster pixel-by-pixel access</RefPurpose>
>     </RefNameDiv>
>     ...

I tried several formats and several editors for those formats. For the
raw data entry they were all terrible. Docbook being one of the roughest
as far as signal-to-noise goes.

While there are "tags" in the code, they are really only "tokens". They
could be any simple "start" and "stop" code. In fact they are really not
tags, because they are unmatched. I think I'll change the tokens to
something that doesn't look like tags.

At this point the documentation source is in the simplest format I could
create. The python parser I wrote for it is only about 180 lines of
Python code. It already supports several features like bulleting,
preformatting, etc.

It would be straightforward to write an exporter out to any format. I
think that may be a good idea too, since one of the main goals is to
make the documentation easier to edit and update.