[Python-Dev] The docs, reloaded

[Nick Craig-Wood]

On Thu, May 24, 2007 at 12:43:18PM -0500, Ron Adam wrote:
> And for console text output, is the unmodified reST suitable, or would it 
> be desired to modify it in some way?

Currently pydoc output looks like a man page under Unix.  if it could
look like that then that would be great.  Otherwise raw reST is fine!

> Should a subset of the main documents be included with pydoc to avoid the 
> documents not available messages if they are not installed?
> 
> Or should the topics retrieval code be moved from pydoc to the main 
> document tools so it's installed with the documents.  Then that can be 
> maintianed with the documents instead of being maintained with pydoc.  Then 
> pydoc will just looks for it, instead of looking for the html pages.

I think the latter proposal sounds like the correct one.  In debian
for instance, the python docs are a seperate package, and it would
seem reasonable that you'd have to have that package installed to get
the long docs.

> > I think that if reST was an acceptable form for the documentation, and
> > it could be auto included in the main docs from docstrings then you
> > would find more modules completely documented in __doc__.
> 
> That would be fine for third party modules if they want to do that or if 
> there is not much difference between the two.

If you look at the documentation for subprocess for instance, you'll
see that the docstring is pretty much the same as the library
reference documentation which seems like needless duplication and
opportunity for code/doc skew.  Maybe one is auto generated from the
other - I don't know!

> > Actually if it gave both sets of docs quick, then long, one after the
> > other that would suit me fine.
> 
> That may work well for the full documentation, but the quick reference 
> wouldn't be a short quick reference any more.

Well you could stop after reading the short bit!

> I'm attempting to have a pydoc api call that gets a single item or sub-item 
> and format it to a desired output so it can be included in other content. 
> That's makes it possible for the full docs (not necessarily pythons) to 
> embed pydoc output in it if it's desirable.  This will need pydoc 
> formatters for the target document type.  I hope to include a reST output 
> formatter for pydoc.
> 
> The help() function is imported from pydoc by site.py when you start 
> python.  It may not be difficult to have it as a function that first tries 
> pydoc to get a request, and if the original request is returned unchanged, 
> tries to get information from the full documentation.  There could be a way 
> to select one or the other, (or both).
> 
> But this feature doesn't need to be built into pydoc, or the full 
> documentation.  They just need to be able to work together so things like 
> this are possible in an easy to write 4 or 5 line function. (give or take a 
> few lines)
> 
> So it looks like most of these issues are more a matter of how to organize 
> the interfaces.  It turns out that what I've done with pydoc, and what 
> Georg is doing with the main documentation should work together quite 
> nicely.

Sounds good!

Nick
-- 
Nick Craig-Wood <nick at craig-wood.com> -- http://www.craig-wood.com/nick