[Yum-devel] yum-utils, man pages, etc.

[Brian Long]

On Wed, 2006-01-04 at 10:16 -0500, Brian Long wrote:
> On Wed, 2006-01-04 at 10:09 -0500, seth vidal wrote:
> > On Wed, 2006-01-04 at 10:04 -0500, Brian Long wrote:
> > > I pulled down yum and yum-utils CVS to start poking at making
> > > improvements.  I'm not a Python programmer -- I come from the Perl side
> > > of things.  It appears Python does not have something similar to POD
> > > which can then be run through utilities like pod2man to extract man
> > > pages.  I found mention of HappyDoc, help2man and others on python.org.
> > > 
> > 
> > Look at epydoc.
> > 
> > That documentation mechanism is one way to do it.
> 
> I started poking further and it appears pydoc might make sense.  Epydoc
> uses pydoc to generate HTML and PDF.  pydoc already outputs a man page.
> If I run "/usr/lib/python2.3/pydoc.py pydoc > man/man1/pydoc.1" and then
> I run "man -M ./man pydoc", I get the man page.  Unfortunately, at the
> top it gives a warning:
> 
> WARNING: old character encoding and/or character set
> 
> I believe it does this because pydoc.py has "coding: Latin-1".  When I
> run pydoc.py sys and view the man page, I don't get the warning.
> 
> As a start, it appears I would just need to add docstrings to the yum-
> utils scripts and run pydoc against each one in the Makefile.  Would
> that be acceptable?

It appears pydoc is primary for documenting the API on a Python Module,
not for documenting a python script will command-line options, etc.
Epydoc would be the same: "Epydoc is a tool for generating API
documentation for Python modules based on their docstrings".

/Brian/
-- 
       Brian Long                      |         |           |
       IT Data Center Systems          |       .|||.       .|||.
       Cisco Linux Developer           |   ..:|||||||:...:|||||||:..
       Phone: (919) 392-7363           |   C i s c o   S y s t e m s