[Python-Dev] The docs, reloaded (original) (raw)

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.

Laurent

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