[Doc-SIG] Python docs in reST

[Martin Blais]

On 5/22/05, Skip Montanaro <skip at pobox.com> wrote:
> >>>>> "Ian" == Ian Bicking <ianb at colorstudy.com> writes:
> It's not like this is a new problem, is it?  It seems to me we should be
> able to come up with a reasonable set of requirements and a design that
> addresses them.  I'd like to avoid hacks that require we deal with HTML as
> an input format.

I agree....  talking about doing "hacks" when we're talking about
replacing something like LaTeX does not sound very appropriate to
me...  LaTeX is a very powerful program.  I think we need to enumerate
the problems that we're having with it now that makes people want to
move away from it (apart from the "it's not an all-python solution"
idea).

In other words, to answer these two questions clearly:

1. why exactly do we want to change the documentation system?  what
are the problems with the current approach?  can it just be fixed with
the current system?  what would be the advantages of a new system?

(I voiced some answers of this question in my previous inquiries,
namely, that there is currently no way to unify part of the docs from
the source, i.e. function descriptions should be in the source and
pulled into the manual sources automatically, to have one single
source for all "bits" of docs.

Other messages seem to suggest that LaTeX is too complicated for
contributors.  I personally disagree, but it may be a valid reason if
this is the case.  IMHO if someone can't be bothered to learn the 20
macros being used in the LaTeX sources used for the Python docs (which
are themselves reasonably well documented and for which ample examples
are available) I have to wonder about their capacity to contribute
readable prose to the documentation.)


2. what is the precise list of features that are offered in the
current documentation system (excluding all the LaTeX features that it
is not using) and how can we replace all of them with the new system
(docutils or otherwise)?

(Again, just my HO (and i'm just an observer more than anything else,
really), but I don't like the idea of replacing a source format to a
new system if the new system doesn't have at least all the features of
the old one.  As much as I enjoy working with docutils, it does not
seem to offer all that LaTeX and its multiple conversions has to offer
now.)

cheers,