rosdoc: epyenator.py Source File

00001 #!/usr/bin/env python
00002 # Software License Agreement (BSD License)
00003 #
00004 # Copyright (c) 2008, Willow Garage, Inc.
00005 # All rights reserved.
00006 #
00007 # Redistribution and use in source and binary forms, with or without
00008 # modification, are permitted provided that the following conditions
00009 # are met:
00010 #
00011 #  * Redistributions of source code must retain the above copyright
00012 #    notice, this list of conditions and the following disclaimer.
00013 #  * Redistributions in binary form must reproduce the above
00014 #    copyright notice, this list of conditions and the following
00015 #    disclaimer in the documentation and/or other materials provided
00016 #    with the distribution.
00017 #  * Neither the name of Willow Garage, Inc. nor the names of its
00018 #    contributors may be used to endorse or promote products derived
00019 #    from this software without specific prior written permission.
00020 #
00021 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00022 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00023 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
00024 # FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
00025 # COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
00026 # INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
00027 # BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00028 # LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00029 # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00030 # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00031 # ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00032 # POSSIBILITY OF SUCH DAMAGE.
00033 #
00034 
00035 from __future__ import with_statement
00036 
00037 import os, sys
00038 from subprocess import Popen, PIPE
00039 
00040 from rosdoc.rdcore import *
00041 
00042 ## Main entrypoint into creating Epydoc documentation
00043 ## @return [str]: list of packages that were successfully generated
00044 def generate_epydoc(ctx):
00045     success = []
00046     for package, path in ctx.packages.iteritems():
00047         if package in ctx.doc_packages and ctx.should_document(package) \
00048                 and ctx.has_builder(package, 'epydoc'):
00049 
00050             # currently only allow one epydoc build per package. This
00051             # is not inherent, it just requires rewriting higher-level
00052             # logic
00053             rd_config = [d for d in ctx.rd_configs[package] if d['builder'] == 'epydoc'][0]
00054 
00055             # Configuration Properties (all optional):
00056             #
00057             # output_dir: directory_name (default: '.')
00058             # name: Documentation Set Name (default: Python API)
00059             try:
00060                 html_dir = html_path(package, ctx.docdir)
00061                 if 'output_dir' in rd_config:
00062                     html_dir = os.path.join(html_dir, rd_config['output_dir'])
00063                 if not os.path.isdir(html_dir):
00064                     os.makedirs(html_dir)
00065                     
00066                 command = ['epydoc', '--html', package, '-o', html_dir]
00067                 if 'exclude' in rd_config:
00068                     for s in rd_config['exclude']:
00069                         command.extend(['--exclude', s])
00070 
00071                 if 'config' in rd_config:
00072                     import roslib.packages
00073                     pkg_dir = roslib.packages.get_pkg_dir(package)
00074                     command.extend(['--config', os.path.join(pkg_dir, rd_config['config']) ])
00075                 else:
00076                     # default options
00077                     command.extend(['--inheritance', 'included', '--no-private'])
00078                 
00079                 # determine the python path of the package
00080                 import roslib.launcher
00081                 # - really dirty here, but the launcher intentionally caches the path for performance
00082                 del roslib.launcher._bootstrapped[:]
00083                 paths = roslib.launcher._generate_python_path(package, [], os.environ) 
00084                 env = os.environ.copy()
00085                 env['PYTHONPATH'] = os.pathsep.join([p for p in paths if os.path.exists(p)])
00086 
00087                 if not ctx.quiet:
00088                     print "epydoc-building %s [%s]"%(package, ' '.join(command))
00089                 Popen(command, stdout=PIPE, env=env).communicate()
00090                 success.append(package)
00091             except Exception, e:
00092                 print >> sys.stderr, "Unable to generate epydoc for [%s]. This is probably because epydoc is not installed.\nThe exact error is:\n\t%s"%(package, str(e))
00093     return success