Committed patches from bugs #210362 and #209671 to make the distutils and python eclasses ready for eclass-manpage.

2 files changed, 103 insertions, 87 deletions

diff --git a/eclass/distutils.eclass b/eclass/distutils.eclass
index e7ec865cf5ec..99a2120024af 100644
--- a/eclass/distutils.eclass
+++ b/eclass/distutils.eclass
@@ -1,26 +1,24 @@
-# Copyright 1999-2004 Gentoo Foundation
+# Copyright 1999-2008 Gentoo Foundation
 # Distributed under the terms of the GNU General Public License v2
-# $Header: /var/cvsroot/gentoo-x86/eclass/distutils.eclass,v 1.45 2008/01/23 22:19:04 hawking Exp $
-#
-# Author: Jon Nelson <jnelson@gentoo.org>
-# Current Maintainer: Alastair Tse <liquidx@gentoo.org>
+# $Header: /var/cvsroot/gentoo-x86/eclass/distutils.eclass,v 1.46 2008/02/28 20:20:32 dev-zero Exp $
+
+# @ECLASS: distutils.eclass
+# @MAINTAINER:
+# Alastair Tse <liquidx@gentoo.org>
 #
+# Original author: Jon Nelson <jnelson@gentoo.org>
+# @BLURB: This eclass allows easier installation of distutils-based python modules
+# @DESCRIPTION:
 # The distutils eclass is designed to allow easier installation of
 # distutils-based python modules and their incorporation into
 # the Gentoo Linux system.
 #
-# - Features:
-# distutils_src_compile()    - does python setup.py build
-# distutils_src_install()    - does python setup.py install and install docs
-# distutils_python_version() - sets PYVER/PYVER_MAJOR/PYVER_MINOR
-# distutils_python_tkinter() - checks for tkinter support in python
-#
-# - Variables:
-# PYTHON_SLOT_VERSION     - for Zope support
-# DOCS                    - additional DOCS
+# It inherits python, multilib, and eutils
 
 inherit python multilib eutils
 
+# @ECLASS-VARIABLE: PYTHON_SLOT_VERSION
+# @DESCRIPTION:
 # This helps make it possible to add extensions to python slots.
 # Normally only a -py21- ebuild would set PYTHON_SLOT_VERSION.
 if [ "${PYTHON_SLOT_VERSION}" = "2.1" ] ; then
@@ -34,6 +32,13 @@ else
 	python="python"
 fi
 
+# @ECLASS-VARIABLE: DOCS
+# @DESCRIPTION:
+# Additional DOCS
+
+# @FUNCTION: distutils_src_unpack
+# @DESCRIPTION:
+# The distutils src_unpack function, this function is exported
 distutils_src_unpack() {
 	unpack ${A}
 	cd "${S}"
@@ -44,10 +49,18 @@ distutils_src_unpack() {
 	echo "def use_setuptools(*args, **kwargs): pass" > ez_setup.py
 }
 
+# @FUNCTION: distutils_src_compile
+# @DESCRIPTION:
+# The distutils src_compile function, this function is exported
 distutils_src_compile() {
 	${python} setup.py build "$@" || die "compilation failed"
 }
 
+# @FUNCTION: distutils_src_install
+# @DESCRIPTION:
+# The distutils src_install function, this function is exported.
+# It also installs the "standard docs" (CHANGELOG, Change*, KNOWN_BUGS, MAINTAINERS,
+# PKG-INFO, CONTRIBUTORS, TODO, NEWS, MANIFEST*, README*, and AUTHORS)
 distutils_src_install() {
 
 	# need this for python-2.5 + setuptools in cases where
@@ -73,8 +86,9 @@ distutils_src_install() {
 	[ -n "${DOCS}" ] && dodoc ${DOCS}
 }
 
-# generic pyc/pyo cleanup script.
-
+# @FUNCTION: distutils_pkg_postrm
+# @DESCRIPTION:
+# Generic pyc/pyo cleanup script. This function is exported.
 distutils_pkg_postrm() {
 	PYTHON_MODNAME=${PYTHON_MODNAME:-${PN}}
 
@@ -93,9 +107,10 @@ distutils_pkg_postrm() {
 	fi
 }
 
-# this is a generic optimization, you should override it if your package
-# installs things in another directory
-
+# @FUNCTION: distutils_pkg_postinst
+# @DESCRIPTION:
+# This is a generic optimization, you should override it if your package
+# installs things in another directory. This function is exported
 distutils_pkg_postinst() {
 	PYTHON_MODNAME=${PYTHON_MODNAME:-${PN}}
 
@@ -112,13 +127,17 @@ distutils_pkg_postinst() {
 	fi
 }
 
-# e.g. insinto ${ROOT}/usr/include/python${PYVER}
-
+# @FUNCTION: distutils_python_version
+# @DESCRIPTION:
+# Calls python_version, so that you can use something like
+#  e.g. insinto ${ROOT}/usr/include/python${PYVER}
 distutils_python_version() {
 	python_version
 }
 
-# checks for if tkinter support is compiled into python
+# @FUNCTION: distutils_python_tkinter
+# @DESCRIPTION:
+# Checks for if tkinter support is compiled into python
 distutils_python_tkinter() {
 	python_tkinter_exists
 }
diff --git a/eclass/python.eclass b/eclass/python.eclass
index ba4b48115bb5..7bcbb1fc9afc 100644
--- a/eclass/python.eclass
+++ b/eclass/python.eclass
@@ -1,22 +1,15 @@
-# Copyright 1999-2004 Gentoo Foundation
+# Copyright 1999-2008 Gentoo Foundation
 # Distributed under the terms of the GNU General Public License v2
-# $Header: /var/cvsroot/gentoo-x86/eclass/python.eclass,v 1.32 2007/05/06 22:11:12 kloeri Exp $
-#
-# Author: Alastair Tse <liquidx@gentoo.org>
-#
-# A Utility Eclass that should be inherited by anything that deals with
-# Python or Python modules.
-#
-# - Features:
-# python_version()        - sets PYVER/PYVER_MAJOR/PYVER_MINOR
-# python_tkinter_exists() - Checks for tkinter support in python
-# python_mod_exists()     - Checks if a python module exists
-# python_mod_compile()    - Compiles a .py file to a .pyc/.pyo
-# python_mod_optimize()   - Generates .pyc/.pyo precompiled scripts
-# python_mod_cleanup()    - Goes through /usr/lib*/python* to remove
-#                           orphaned *.pyc *.pyo
-# python_makesym()        - Makes /usr/bin/python symlinks
+# $Header: /var/cvsroot/gentoo-x86/eclass/python.eclass,v 1.33 2008/02/28 20:20:32 dev-zero Exp $
 
+# @ECLASS: python.eclass
+# @MAINTAINER:
+# python@gentoo.org
+#
+# original author: Alastair Tse <liquidx@gentoo.org>
+# @BLURB: A Utility Eclass that should be inherited by anything that deals with Python or Python modules.
+# @DESCRIPTION:
+# Some useful functions for dealing with python.
 inherit alternatives multilib
 
 
@@ -43,11 +36,11 @@ __python_eclass_test() {
 	echo " PYVER_MINOR: $PYVER_MINOR PYVER_MICRO: $PYVER_MICRO"
 }
 
-#
-# name:   python_disable/enable_pyc
-# desc:   tells python not to automatically recompile modules to .pyc/.pyo
-#         even if the timestamps/version stamps don't match. this is
-#         done to protect sandbox.
+# @FUNCTION: python_disable_pyc
+# @DESCRIPTION:
+# Tells python not to automatically recompile modules to .pyc/.pyo
+# even if the timestamps/version stamps don't match. This is done
+# to protect sandbox.
 #
 # note:   supported by >=dev-lang/python-2.2.3-r3 only.
 #
@@ -55,18 +48,20 @@ python_disable_pyc() {
 	export PYTHON_DONTCOMPILE=1
 }
 
+# @FUNCTION: python_enable_pyc
+# @DESCRIPTION:
+# Tells python to automatically recompile modules to .pyc/.pyo if the
+# timestamps/version stamps change
 python_enable_pyc() {
 	unset PYTHON_DONTCOMPILE
 }
 
 python_disable_pyc
 
-#
-# name:   python_version
-# desc:   run without arguments and it will export the version of python
-#         currently in use as $PYVER
-#
-
+# @FUNCTION: python_version
+# @DESCRIPTION:
+# Run without arguments and it will export the version of python
+# currently in use as $PYVER; sets PYVER/PYVER_MAJOR/PYVER_MINOR
 __python_version_extract() {
 	verstr=$1
 	export PYVER_MAJOR=${verstr:0:1}
@@ -85,21 +80,19 @@ python_version() {
 	__python_version_extract $PYVER_ALL
 }
 
-#
-# name:   python_makesym
-# desc:   run without arguments, it will create the /usr/bin/python symlinks
-#         to the latest installed version
-#
+# @FUNCTION: python_makesym
+# @DESCRIPTION:
+# Run without arguments, it will create the /usr/bin/python symlinks
+# to the latest installed version
 python_makesym() {
 	alternatives_auto_makesym "/usr/bin/python" "python[0-9].[0-9]"
 	alternatives_auto_makesym "/usr/bin/python2" "python2.[0-9]"
 }
 
-#
-# name:   python_tkinter_exists
-# desc:   run without arguments, checks if python was compiled with Tkinter
-#         support.  If not, prints an error message and dies.
-#
+# @FUNCTION: python_tkinter_exists
+# @DESCRIPTION:
+# Run without arguments, checks if python was compiled with Tkinter
+# support.  If not, prints an error message and dies.
 python_tkinter_exists() {
 	if ! python -c "import Tkinter" >/dev/null 2>&1; then
 		eerror "You need to recompile python with Tkinter support."
@@ -110,17 +103,18 @@ python_tkinter_exists() {
 	fi
 }
 
+# @FUNCTION: python_mod_exists
+# @USAGE: < module >
+# @DESCRIPTION:
+# Run with the module name as an argument. it will check if a
+# python module is installed and loadable. it will return
+# TRUE(0) if the module exists, and FALSE(1) if the module does
+# not exist.
 #
-# name:   python_mod_exists
-# desc:   run with the module name as an argument. it will check if a
-#         python module is installed and loadable. it will return
-#         TRUE(0) if the module exists, and FALSE(1) if the module does
-#         not exist.
-# exam:
+# Example:
 #         if python_mod_exists gtk; then
 #             echo "gtk support enabled"
 #         fi
-#
 python_mod_exists() {
 	[ -z "$1" ] && die "${FUNCTION} requires an argument!"
 	if ! python -c "import $1" >/dev/null 2>&1; then
@@ -129,11 +123,13 @@ python_mod_exists() {
 	return 0
 }
 
+# @FUNCTION: python_mod_compile
+# @USAGE: < file >
+# @DESCRIPTION:
+# Given a filename, it will pre-compile the module's .pyc and .pyo.
+# should only be run in pkg_postinst()
 #
-# name:   python_mod_compile
-# desc:   given a filename, it will pre-compile the module's .pyc and .pyo.
-#         should only be run in pkg_postinst()
-# exam:
+# Example:
 #         python_mod_compile ${ROOT}usr/lib/python2.3/site-packages/pygoogle.py
 #
 python_mod_compile() {
@@ -154,17 +150,18 @@ python_mod_compile() {
 	fi
 }
 
+# @FUNCTION: python_mod_optimize
+# @USAGE: [ path ]
+# @DESCRIPTION:
+# If no arguments supplied, it will recompile all modules under
+# sys.path (eg. /usr/lib/python2.3, /usr/lib/python2.3/site-packages/ ..)
+# no recursively
 #
-# name:   python_mod_optimize
-# desc:   if no arguments supplied, it will recompile all modules under
-#         sys.path (eg. /usr/lib/python2.3, /usr/lib/python2.3/site-packages/ ..)
-#         no recursively
+# If supplied with arguments, it will recompile all modules recursively
+# in the supplied directory
 #
-#         if supplied with arguments, it will recompile all modules recursively
-#         in the supplied directory
-# exam:
+# Example:
 #         python_mod_optimize ${ROOT}usr/share/codegen
-#
 python_mod_optimize() {
 	local myroot
 	# strip trailing slash
@@ -190,15 +187,15 @@ python_mod_optimize() {
 	eend $?
 }
 
+# @FUNCTION: python_mod_cleanup
+# @USAGE: [ dir ]
+# @DESCRIPTION:
+# Run with optional arguments, where arguments are directories of
+# python modules. if none given, it will look in /usr/lib/python[0-9].[0-9]
 #
-# name:   python_mod_cleanup
-# desc:   run with optional arguments, where arguments are directories of
-#         python modules. if none given, it will look in /usr/lib/python[0-9].[0-9]
-#
-#         it will recursively scan all compiled python modules in the directories
-#         and determine if they are orphaned (eg. their corresponding .py is missing.)
-#         if they are, then it will remove their corresponding .pyc and .pyo
-#
+# It will recursively scan all compiled python modules in the directories
+# and determine if they are orphaned (eg. their corresponding .py is missing.)
+# if they are, then it will remove their corresponding .pyc and .pyo
 python_mod_cleanup() {
 	local SEARCH_PATH myroot