[Python-Dev] The docs, reloaded

Laurent Gautier lgautier at gmail.com
Mon May 21 11:23:03 CEST 2007

I would agree with the point that python core should be considered
first, but I would also only see beneficial to leave the door open
to the need of other packages.

I have (briefly but intensely) worked on a revamp of pydoc earlier on
this year, and while collecting requirements from a number of places
having maths expressions or else appeared important for a number
of cases (and a very reasonable request in a case) .

That particular point leads to something that I see important for what
a new/better documentation system should provide: a good and
modular interface to access the documentation, process it,
and navigate it.

When looking at the particular example discussed here, it could be
implemented by allowing a "pluggable" processing components for
docstrings (and let a given package developer the possibility to use as
much as the default documentation machinery as possible and
implement the processing mathml, latex, whatever, as wanted).
One can consider the possibility to have the "custom" processing of
the docstring embedded in the package itself.


2007/5/21, Brett Cannon <brett at python.org>:
> On 5/20/07, "Martin v. Löwis" <martin at v.loewis.de> wrote:
> > >     Georg> So, that's not really a concern of mine ;)
> > >
> > > You must realize that people will use the core tools to create
> documentation
> > > for third party packages which aren't in the core.  If you replace LaTeX
> > > with something else I think you need to keep math in mind whether it's
> used
> > > in the core documentation or not.
> >
> > I disagree. The documentation infrastructure of Python should only
> > consider the needs of Python itself. If other people can use that
> > infrastructure for other purposes, fine - if they find that it does
> > not meet their needs, they have to look elsewhere.
> Martin beat me to my comment.  =)  Python's needs should come first, period.
>  If Georg wants to add math support, fine.  But honestly I would rather he
> spend his time on Python-specific stuff then get bogged down to support
> possible third parties.
> -Brett
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe:
> http://mail.python.org/mailman/options/python-dev/lgautier%40gmail.com

More information about the Python-Dev mailing list