[Doc-SIG] Eliding most of distutils and Carbon from the global module index

[Fred L. Drake, Jr.]

On Thursday 08 December 2005 13:57, skip at pobox.com wrote:
 > The global module index contains around 360 entries.  46 of them are for
 > various modules in the distutils package.  Another 24 are for Carbon (Mac)
 > modules.  I think almost all those references come from lines in
 > Doc/dist/dist.tex or Doc/mac/toolbox.tex like:
 >
 >     \declaremodule{standard}{distutils.core}
 >
 > or
 >
 >     \declaremodule{standard}{Carbon.CF}

That's correct.  That's not the only thing these lines are used to do, 
however.

 > I think many/most of those modules could be omitted from the module index
 > without major problems.  The question is how to do that?  Should I
 >
 >     * remove the \declaremodule lines from the .tex files

No.

 >     * redefine the \declaremodule macro to accept an optional arg that can
 >       suppress the generation of an index entry

No.

 >     * define a new macro (\declaremodulenoindex?) that does everything
 >       the current one does except the index entry dance

No.

 > ?  I'd like to do something.  Take a look at the docs for distutils.debug:
 >
 >     http://www.python.org/dev/doc/devel/dist/module-distutils.debug.html
 >
 > and these for Carbon.CF:
 >
 >     http://www.python.org/dev/doc/devel/mac/module-Carbon.CF.html
 >
 > Hardly seems worth mentioning in the module index at all, let alone on par
 > with sys, os, math, etc.

It should be easy to remove the distutils modules simply by editing the 
command used to generate html/modindex.html in Doc/Makefile.

Dealing with the Carbon modules may be more difficult.  Perhaps adding an 
"exclude" filter to Doc/tools/mkmodindex would be sufficient.  It would need 
to be set from the command line.

In the long run, though, we really just need to complete the documentation for 
those modules without sufficient documentation.  Patches welcome.  :-)


  -Fred

-- 
Fred L. Drake, Jr.   <fdrake at acm.org>