[Doc-SIG] Python docs in reST?

[Martin Blais]

On 5/16/05, Michael Hudson <mwh at python.net> wrote:
> Skip Montanaro <skip at pobox.com> writes:
> >     * possibly enlarge pool of documentation contributors
> 
> Yeah, right.  This is where my lack of faith in humanity comes out.
> 
> I believe there has been a long-ish term standing offer from assorted
> people to turn plain text docs into suitable latex for the docs (if
> not, let me make one).
> 
> The main reason that Python's documentation is patchy in places is
> because writing good content is hard!  Dealing with *any* format is
> minor in comparison.

i agree!

however, we could make it just a little bit easier:  i only recently
started using the Docs directory to document some code, and I was
bothered by a few things:

1. you have to keep a copy of the Python soruce code lying around to
make it work;

2. it doesn't "just work", you have to rip a lot of stuff out of the
given makefile to make it do the minimal thing for a new documentation
set, and it has a lot of stuff that I didn't need, like isilo, custom
bits for the python docs, etc.  It took me a little while to get it
going, it would have been nicer to do something like "emerge
python-doc-system" and copy a few clear rules from somewhere else.

If we could somehow separate the code that is needed for generating
the Python docs (and not taking along all the custom bits that are
specific to that/those documents), and package that separately, that
would help a tiny little bit.

just an idea.

cheers,