landing_page.py
Go to the documentation of this 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 import time
00039 
00040 from subprocess import Popen, PIPE
00041 
00042 import roslib.msgs
00043 import roslib.srvs
00044 from rosdoc.rdcore import *
00045 
00046 def _href(location, text):
00047     return '<a href="%(location)s">%(text)s</a>'%locals()
00048 
00049 def link_name(rd_config):
00050     if 'name' in rd_config:
00051         n = rd_config['name']
00052     else:
00053         if rd_config['builder'] == 'doxygen':
00054             return 'C++ API'
00055         elif rd_config['builder'] in ['epydoc', 'sphinx']:
00056             return 'Python API'
00057         elif rd_config['builder'] in ['external']:
00058             return rd_config.get('external_label', 'External')
00059         else:
00060             return rd_config['builder']
00061     return n
00062     
00063 def output_location(config):
00064     if config['builder'] == 'external':
00065         return config.get('external_url', None)
00066     else:
00067         return config.get('output_dir', None)
00068     
00069 def generate_links(ctx, package, base_dir, rd_configs):
00070     # rosmake is the one builder that doesn't have an output_dir
00071     # specification, nor output for that matter, so filter it out from
00072     # landing page processing
00073     configs = [c for c in rd_configs if c['builder'] != 'rosmake']
00074     
00075     output_dirs = [output_location(c) for c in configs]
00076     # filter out empties
00077     output_dirs = [d for d in output_dirs if d and d != '.']
00078     
00079     # length check. if these are unequal, cannot generate landing
00080     # page. this is often true if the config is merely generating
00081     # local. Ignore 'rosmake' builder as it doesn't have output spec
00082     if len(output_dirs) != len(configs):
00083         return None
00084 
00085     links = [_href(d, link_name(c)) for c, d in zip(configs, output_dirs)]
00086         
00087     msgs = roslib.msgs.list_msg_types(package, False)
00088     srvs = roslib.srvs.list_srv_types(package, False)
00089     if msgs or srvs:
00090         if msgs and srvs:
00091             title = 'msg/srv API'
00092         elif msgs and not srvs:
00093             title = 'msg API'    
00094         elif srvs and not msgs:
00095             title = 'srv API'
00096         #TODO: this shouldn't be hardcoded to index-msg.html
00097         links.append(_href('index-msg.html', title))
00098 
00099     url = ctx.manifests[package].url
00100     if url:
00101         links.append(_href(url, '%s Package Documentation'%package))
00102     return links
00103 
00104 ## Generate landing page in the event that there are multiple documentation sets
00105 ## @return [str]: list of packages for which there are landing pages generated
00106 def generate_landing_page(ctx):
00107     success = []
00108     template = load_tmpl('landing.template')
00109     #print "landing_page: packages are", ctx.packages.keys()
00110     for package in ctx.packages.iterkeys():
00111         #print "landing page", package
00112         try:
00113             if package in ctx.doc_packages and ctx.should_document(package) and \
00114                 package in ctx.rd_configs:
00115                 rd_configs = ctx.rd_configs[package]
00116                 links = generate_links(ctx, package, ctx.docdir, rd_configs)
00117                 # if links is empty, it means that the rd_configs builds
00118                 # to the base directory and no landing page is required
00119                 # (or it means that the config is corrupt)
00120                 if not links:
00121                     #print "ignoring landing page for", package
00122                     continue
00123 
00124                 html_dir = html_path(package, ctx.docdir)
00125                 #print "generating landing page", html_dir
00126 
00127                 if not os.path.isdir(html_dir):
00128                     os.makedirs(html_dir)
00129 
00130                 links_html = '\n'.join(['<li class="landing-li">%s</li>'%l for l in links])
00131                 date = str(time.strftime('%a, %d %b %Y %H:%M:%S'))                
00132                 vars = {
00133                     '$package': package,
00134                     '$links': links_html,
00135                     '$date': date,
00136                         }
00137 
00138                 with open(os.path.join(html_dir, 'index.html'), 'w') as f:
00139                     f.write(instantiate_template(template, vars))
00140                 success.append(package)
00141         except Exception, e:
00142             print >> sys.stderr, "Unable to generate landing_page for [%s]:\n\t%s"%(package, str(e))
00143     return success


rosdoc
Author(s): Ken Conley/kwc@willowgarage.com
autogenerated on Sun Oct 5 2014 23:30:30