def _generateAllMembersDocs(self):
"""
Generates the all members documentation for this document.
:return <str>
"""
if ( not inspect.isclass(self._object) ):
return ''
members = self._collectMembers(self._object)
member_docs = []
members.sort( lambda x, y: cmp( x.name, y.name ) )
for member in members:
if ( member.name.startswith('__') and member.name.endswith('__') ):
continue
member_doc = self._generateAllMemberSummary(member)
if ( member_doc ):
member_docs.append('<li>%s</li>' % member_doc)
environ = commands.ENVIRON.copy()
environ['members_left'] = '\n'.join( member_docs[:len(member_docs)/2])
environ['members_right'] = '\n'.join( member_docs[len(member_docs)/2:])
environ['title'] = self.title()
environ['base_url'] = self.baseurl()
environ['static_url'] = environ['base_url'] + '/_static'
environ['navigation'] %= environ
return templates.template('allmembers.html') % environ
def _generateSourceDocs( self ):
"""
Return the documentation containing the source code.
:return <str>
"""
if ( not inspect.ismodule(self._object) ):
return ''
# load the code file
codefilename = os.path.splitext( self._object.__file__ )[0]
codefilename += '.py'
codefile = open(codefilename, 'r')
code = codefile.read()
codefile.close()
environ = commands.ENVIRON.copy()
environ['code'] = xml.sax.saxutils.escape(code)
environ['title'] = self.title()
environ['base_url'] = self.baseurl()
environ['static_url'] = environ['base_url'] + '/_static'
environ['breadcrumbs'] = self.breadcrumbs(includeSelf = True)
environ['navigation'] %= environ
return templates.template('source.html') % environ
def generateDocumentIndex(outpath, page ):
"""
Generates the main API index document.
"""
# generate the indexes and global files
environ = ENVIRON.copy()
environ['base_url'] = '.'
environ['static_url'] = './_static'
environ['navigation'] %= environ
contents = templates.template('index.html') % environ
environ = ENVIRON.copy()
environ['title'] = 'Documentation Main Page'
environ['base_url'] = '.'
environ['static_url'] = './_static'
environ['breadcrumbs'] = breadcrumbs([('', 'Home')])
environ['contents'] = contents
environ['navigation'] %= environ
html = page % environ
indexfile = open(os.path.join(outpath, 'index.html'), 'w')
indexfile.write(html)
indexfile.close()
def generateDocumentIndex(outpath, page):
"""
Generates the main API index document.
"""
# generate the indexes and global files
environ = ENVIRON.copy()
environ['base_url'] = '.'
environ['static_url'] = './_static'
environ['navigation'] %= environ
contents = templates.template('index.html') % environ
environ = ENVIRON.copy()
environ['title'] = 'Documentation Main Page'
environ['base_url'] = '.'
environ['static_url'] = './_static'
environ['breadcrumbs'] = breadcrumbs([('', 'Home')])
environ['contents'] = contents
environ['navigation'] %= environ
html = page % environ
indexfile = open(os.path.join(outpath, 'index.html'), 'w')
indexfile.write(html)
indexfile.close()
def _generateModuleDocs( self ):
"""
Generates module documentation for this object.
"""
html = []
# generate the module environ
environ = commands.ENVIRON.copy()
environ['title'] = self.title()
environ['base_url'] = self.baseurl()
environ['static_url'] = environ['base_url'] + '/_static'
environ['breadcrumbs'] = self.breadcrumbs()
environ['url'] = self.url()
environ['doctype'] = 'Module'
if ( '__init__' in self._object.__file__ ):
environ['doctype'] = 'Package'
url_split = environ['url'].split('/')
sources_url = './%s-source.html' % url_split[-1].split('.')[0]
environ['sources'] = sources_url
environ['navigation'] %= environ
html.append( templates.template('header_module.html') % environ )
# generate the summary report
gdata = self.groupedData()
for key in sorted( gdata.keys(), key = lambda x: DATA_ORDER.index(x)):
value = gdata[key]
html.append( self._generateSummary( key, gdata[key] ) )
# generate the main documentation
maindocs = self._generateObjectDocs( self._object )
if ( maindocs ):
environ = commands.ENVIRON.copy()
environ['type'] = 'Module'
environ['contents'] = maindocs
html.append( templates.template('docs_main.html') % environ )
# generate the member documentation
html.append( self._generateMemberDocs('Module Function Documentation',
self.data().values()))
return '\n'.join(html)
def breadcrumbs(crumbs):
"""
Creates a breadcrumb string for the inputed crumbs.
:param crumbs | [(<str> relative url, <str> title), ..]
"""
crumb_str = []
crumb_templ = templates.template('link_breadcrumbs.html')
for url, text in crumbs:
if (url != ''):
crumb_str.append(crumb_templ % {'url': url, 'text': text})
else:
crumb_str.append(crumb_templ % {'url': '#', 'text': text})
return ''.join(crumb_str)
def breadcrumbs( crumbs ):
"""
Creates a breadcrumb string for the inputed crumbs.
:param crumbs | [(<str> relative url, <str> title), ..]
"""
crumb_str = []
crumb_templ = templates.template('link_breadcrumbs.html')
for url, text in crumbs:
if ( url != '' ):
crumb_str.append(crumb_templ % {'url': url, 'text': text})
else:
crumb_str.append(crumb_templ % {'url': '#', 'text': text})
return ''.join(crumb_str)
def initEnviron(self):
"""
Initializes the docgen build environment settings with this
dox file's configuration information.
"""
# setup the templating
templates.setTheme(self.theme())
templates.setThemePath(self.themePath())
# initialize navigation
templ = templates.template('link_navigation.html')
nav = []
for title, url in self.navigation():
nav.append(templ % {'title': title, 'url': url})
# set the environment variables
commands.ENVIRON.clear()
commands.ENVIRON['module_title'] = self.title()
commands.ENVIRON['module_version'] = self.version()
commands.ENVIRON['copyright'] = self.copyright()
commands.ENVIRON['navigation'] = ''.join(nav)
# setup rendering options
commands.RENDER_OPTIONS.clear()
commands.RENDER_OPTIONS['TITLE'] = self.title()
commands.RENDER_OPTIONS['VERSION'] = self.version()
commands.RENDER_OPTIONS['COMPANY'] = self.company()
commands.RENDER_OPTIONS['COMPANY_URL'] = self.companyUrl()
split_ver = self.version().split('.')
for i, key in enumerate(('MAJOR', 'MINOR', 'REVISION')):
try:
commands.RENDER_OPTIONS[key] = split_ver[i]
except:
continue
# include additional environment options
for key, value in self.defaultEnvironment().items():
env_key = 'DOX_%s' % key
value = os.environ.get(env_key, value)
commands.ENVIRON[key] = value
commands.RENDER_OPTIONS[key] = value
def initEnviron(self):
"""
Initializes the docgen build environment settings with this
dox file's configuration information.
"""
# setup the templating
templates.setTheme(self.theme())
templates.setThemePath(self.themePath())
# initialize navigation
templ = templates.template('link_navigation.html')
nav = []
for title, url in self.navigation():
nav.append(templ % {'title': title, 'url': url})
# set the environment variables
commands.ENVIRON.clear()
commands.ENVIRON['module_title'] = self.title()
commands.ENVIRON['module_version'] = self.version()
commands.ENVIRON['copyright'] = self.copyright()
commands.ENVIRON['navigation'] = ''.join(nav)
# setup rendering options
commands.RENDER_OPTIONS.clear()
commands.RENDER_OPTIONS['TITLE'] = self.title()
commands.RENDER_OPTIONS['VERSION'] = self.version()
commands.RENDER_OPTIONS['COMPANY'] = self.company()
commands.RENDER_OPTIONS['COMPANY_URL'] = self.companyUrl()
split_ver = self.version().split('.')
for i, key in enumerate(('MAJOR', 'MINOR', 'REVISION')):
try:
commands.RENDER_OPTIONS[key] = split_ver[i]
except:
continue
# include additional environment options
for key, value in self.defaultEnvironment().items():
env_key = 'DOX_%s' % key
value = os.environ.get(env_key, value)
commands.ENVIRON[key] = value
commands.RENDER_OPTIONS[key] = value
def _generateClassDocs( self ):
"""
Generates class documentation for this object.
"""
html = []
self.parseData()
# determine the inheritance
bases = []
for base in self._bases( self._object ):
doc = commands.findDocument(base)
if ( doc ):
opt = {}
opt['text'] = base.__name__
opt['url'] = doc.url( relativeTo = self )
bases.append( templates.template('link_standard.html') % opt )
else:
bases.append( base.__name__ )
if ( len(bases) > 1 ):
basestxt = ', '.join(bases[:-1])
inherits = 'Inherits %s and %s.' % (basestxt, bases[-1])
elif (len(bases) == 1):
inherits = 'Inherits %s.' % bases[0]
else:
inherits = ''
# determine the subclasses
subclasses = []
for subcls in self._subclasses( self._object ):
doc = commands.findDocument(subcls)
if ( doc ):
opt = {}
opt['text'] = subcls.__name__
opt['url'] = doc.url( relativeTo = self )
subclasses.append( templates.template('link_standard.html') % opt )
else:
subclasses.append( subcls.__name__ )
if ( len(subclasses) > 1 ):
subs = ', '.join(subclasses[:-1])
inherited_by = 'Inherited by %s and %s.' % (subs, subclasses[-1])
elif ( len(subclasses) == 1 ):
inherited_by = 'Inherited by %s.' % (subclasses[0])
else:
inherited_by = ''
allmembers = self.objectName().split('.')[-1] + '-allmembers.html'
# generate the module environ
environ = commands.ENVIRON.copy()
environ['title'] = self.title()
environ['allmembers'] = './' + allmembers
environ['breadcrumbs'] = self.breadcrumbs()
environ['url'] = self.url()
environ['doctype'] = 'Class'
environ['inherits'] = inherits
environ['inherited_by'] = inherited_by
modname = self._object.__module__
moddoc = Document.cache.get(modname)
if ( moddoc ):
modurl = moddoc.url(relativeTo = self)
environ['module'] = '<a href="%s">%s</a>' % (modurl, modname)
else:
environ['module'] = modname
html.append( templates.template('header_class.html') % environ )
# generate the summary report
gdata = self.groupedData()
keys = [key for key in gdata.keys() if key in DATA_ORDER]
keys.sort(lambda x, y: cmp(DATA_ORDER.index(x), DATA_ORDER.index(y)))
for key in keys:
html.append( self._generateSummary( key, gdata[key] ) )
# generate the main documentation
maindocs = self._generateObjectDocs( self._object )
if ( maindocs ):
environ = commands.ENVIRON.copy()
environ['type'] = 'Class'
environ['contents'] = maindocs
html.append( templates.template('docs_main.html') % environ )
# generate the member documentation
funcs = self.data().values()
html.append( self._generateMemberDocs( 'Member Documentation',
funcs))
# generate the document environ
return '\n'.join(html)
def generateModuleDocs(outpath, page, basemod):
"""
Generates the module index html document based on the currently loaded
module documents.
"""
from projex.docgen.document import Document
modules = {}
for doc in Document.cache.values():
obj = doc.object()
if ( inspect.ismodule(obj) and obj.__name__.startswith(basemod) ):
first = obj.__name__.split('.')[-1][0].upper()
modules.setdefault(first, [])
modules[first].append(doc)
module_html = []
letters = []
keys = modules.keys()
keys.sort()
for key in keys:
docs = modules[key]
docs.sort( lambda x, y: cmp( x.title(), y.title() ) )
contents = []
for doc in docs:
opts = {}
opts['text'] = doc.title()
opts['url'] = './' + doc.url()
contents.append( templates.template('link_standard.html') % opts )
letter_opts = {}
letter_opts['text'] = key
letter_opts['url'] = '#%s' % key
letters.append( templates.template('link_standard.html') % letter_opts )
modules_opts = {}
modules_opts['letter'] = key
modules_opts['contents'] = '' + '<br/>'.join(contents)
module_text = templates.template('letter_group.html') % modules_opts
module_html.append( module_text )
cls_data = ENVIRON.copy()
cls_data['base_url'] = '..'
cls_data['static_url'] = '../_static'
cls_data['contents'] = '\n'.join(module_html)
cls_data['letters'] = ' . '.join(letters)
cls_data['navigation'] %= cls_data
cls_html = templates.template('modules.html') % cls_data
modules_opt = ENVIRON.copy()
modules_opt['title'] = 'API Modules'
modules_opt['base_url'] = '..'
modules_opt['static_url'] = '../_static'
modules_opt['contents'] = cls_html
modules_opt['navigation'] %= modules_opt
modules_opt['breadcrumbs'] = breadcrumbs([('../index.html', 'Home'),
('./index.html', 'API'),
('', 'All Modules')])
html = page % modules_opt
modulesfile = open(os.path.join(outpath, 'api/modules.html'), 'w')
modulesfile.write(html)
modulesfile.close()
def render(self,
title,
contents,
breadcrumbs=None,
baseUrl=None,
staticUrl=None,
filepath='',
includeTitleInCrumbs=False,
debug=False):
"""
Renders the inputed text to HTML for this dox, including the
inputed breadcrumbs when desired.
:param title | <str>
contents | <DoxSource.Type>
breadcrumbs | [<str>, ..] || None
:return <str>
"""
self.initEnviron()
curdir = os.curdir
if self.filename():
os.chdir(os.path.dirname(self.filename()))
# generate temp breadcrumbs
offset = 1
if breadcrumbs is None:
filepath = str(filepath)
breadcrumbs = []
dir_name = os.path.dirname(filepath)
fname = os.path.basename(filepath).split('.')[0]
if fname.lower() != 'index':
breadcrumbs.append(projex.text.pretty(fname))
offset = 2
index_file = os.path.abspath(os.path.join(dir_name, '../index.wiki'))
while os.path.exists(index_file):
crumb = os.path.normpath(dir_name).split(os.path.sep)[-1]
dir_name = os.path.abspath(os.path.join(dir_name, '..'))
breadcrumbs.append(projex.text.pretty(crumb))
index_file = os.path.abspath(os.path.join(dir_name, '../index.wiki'))
breadcrumbs.append('Home')
breadcrumbs.reverse()
count = len(breadcrumbs) - offset
if baseUrl is None:
baseUrl = '.' + '/..' * count
if staticUrl is None:
staticUrl = baseUrl + '/_static'
page_templ = templates.template('page.html')
crumb_templ = templates.template('link_breadcrumbs.html')
nav_templ = templates.template('link_navigation.html')
# extract the mako template information
templatePaths = self.templatePaths()
rem_paths = []
for path in templatePaths:
if not path in sys.path:
sys.path.insert(0, path)
rem_paths.append(path)
options = commands.RENDER_OPTIONS.copy()
options['FILENAME'] = filepath
options['ROOT'] = baseUrl
if debug:
dir_name = os.path.dirname(filepath)
url = os.path.abspath(dir_name + baseUrl + '/../resources')
commands.url_handler.setReplaceWikiSuffix(False)
commands.url_handler.setStaticUrl('file:///' + url)
else:
commands.url_handler.setStaticUrl(baseUrl + '/_static')
contents = projex.wikitext.render(contents,
commands.url_handler,
options=options,
templatePaths=templatePaths)
if debug:
commands.url_handler.setStaticUrl(None)
commands.url_handler.setReplaceWikiSuffix(True)
# generate the breadcrumb links
crumbs = []
for i, crumb in enumerate(breadcrumbs):
url = '.' + '/..' * (count - i) + '/index.html'
opts = {'text': crumb, 'url': url}
crumbs.append(crumb_templ % opts)
if includeTitleInCrumbs:
crumbs.append(crumb_templ % {'text': title, 'url': ''})
# generate the environ data
environ = commands.ENVIRON.copy()
environ['base_url'] = baseUrl
environ['static_url'] = staticUrl
environ['title'] = title
environ['contents'] = contents
environ['breadcrumbs'] = ''.join(crumbs)
environ['module_title'] = self.title()
environ['module_version'] = self.version()
environ['copyright'] = self.copyright()
# create navigation links
nav = []
for title, url in self.navigation():
href = url % environ
nav.append(nav_templ % {'title': title, 'url': href})
environ['navigation'] = ''.join(nav)
os.chdir(curdir)
# generate the html
result = page_templ % environ
sys.path = sys.path[len(rem_paths):]
return result
def init_environ(module, config):
"""
Initializes the global environ with the given config module. If the given
module is None, then the default_config will be used.
:param module | <module>
:param config | <module> || None
"""
if (not config):
config = default_config
#---------------------------------------------------------------------------
# genrate module information
try:
module_title = config.MODULE_TITLE
except AttributeError:
module_title = module.__name__
try:
module_version = config.MODULE_VERSION
except AttributeError:
try:
module_version = module.__version__
except AttributeError:
module_version = '0.0.0'
#---------------------------------------------------------------------------
# generate copyright information
copyright = []
try:
show_docgen_link = config.SHOW_DOCGEN_LINK
except AttributeError:
show_docgen_link = True
if (show_docgen_link):
link = projex.website()
copyright.append('generated by <a href="%s">docgen</a>' % link)
try:
title = config.COMPANY_TITLE
except AttributeError:
title = 'Projex Software, LLC'
try:
url = config.COMPANY_URL
except AttributeError:
url = projex.website()
year = datetime.date.today().year
opts = (year, url, title)
copyright.append('copyright © %i <a href="%s">%s</a>' % opts)
#---------------------------------------------------------------------------
# grab the theme information
try:
theme = config.THEME
except AttributeError:
theme = 'base'
try:
theme_path = config.THEME_PATH
except AttributeError:
theme_path = ''
#---------------------------------------------------------------------------
# generate the title bar links
try:
links = config.NAVIGATION_LINKS
except AttributeError:
links = []
templ = templates.template('link_navigation.html')
navigation_links = []
for title, url in links:
navigation_links.append(templ % {'title': title, 'url': url})
#---------------------------------------------------------------------------
ENVIRON.clear()
ENVIRON['navigation'] = ''.join(navigation_links)
ENVIRON['copyright'] = ' '.join(copyright)
ENVIRON['module_title'] = module_title
ENVIRON['module_version'] = module_version
templates.setTheme(theme)
templates.setThemePath(theme_path)
def generateUserDocs(path,
target,
page=None,
breadcrumbs=None,
basepath='.',
title=''):
"""
Generates the user documentation for the inputed path by \
rendering any wiki text files to html and saving it out to the doc \
root.
:param path | <str>
target | <str>
page | <str>
source | <str>
breadcrumbs | [<str>, .. ] || None
"""
logger.info('Generating user documentation...')
if page is None:
page = templates.template('page.html')
if not os.path.exists(target):
os.mkdir(target)
if breadcrumbs == None:
breadcrumbs = []
crumb_templ = templates.template('link_breadcrumbs.html')
# setup the base crumbs
base_url = basepath + '/..' * len(breadcrumbs)
static_url = base_url + '/_static'
url_handler.setRootUrl(base_url)
# setup the title
if not title:
main_title = 'Home'
if breadcrumbs:
main_title = os.path.normpath(path).split(os.path.sep)[-1]
main_title = text.pretty(main_title)
else:
main_title = title
entry_contents = []
has_index_file = False
for entry in sorted(os.listdir(path)):
filepath = os.path.join(path, entry)
# skip the svn information
if (entry == '.svn'):
continue
# check for manual index overrides
elif (entry == 'index.wiki'):
has_index_file = True
# add wiki pages to the system
elif (entry.endswith('.wiki')):
filename = os.path.join(path, entry)
outfilename = os.path.join(target, entry.replace('.wiki', '.html'))
wiki_file = open(filename, 'r')
wiki_contents = wiki_file.read()
wiki_file.close()
crumbs = []
count = len(breadcrumbs)
for i, crumb in enumerate(breadcrumbs):
crumbs.append(crumb % (basepath + '/..' * count))
# add the base crumb
crumb = crumb_templ % {
'url': '%s/index.html' % basepath,
'text': main_title
}
crumbs.append(crumb)
# add the page crumb
crumb = crumb_templ % {'url': '#', 'text': title}
crumbs.append(crumb)
crumbstr = ''.join(crumbs)
# generate the contents
title = text.capitalizeWords(entry.split('.')[0])
options = RENDER_OPTIONS.copy()
options['FILENAME'] = filepath
options['ROOT'] = base_url
contents = wikitext.render(wiki_contents,
url_handler,
options=options)
# update the environ
environ = ENVIRON.copy()
environ['title'] = title
environ['contents'] = contents
environ['base_url'] = base_url
environ['static_url'] = static_url
environ['breadcrumbs'] = crumbstr
environ['navigation'] %= environ
url = entry.replace('.wiki', '.html')
entry_item = '<a href="%s/%s">%s</a>' % (basepath, url, title)
entry_contents.append(entry_item)
html = page % environ
html_file = open(outfilename, 'w')
html_file.write(html)
html_file.close()
continue
# copy static paths
elif (entry == '_static'):
targetpath = os.path.join(target, '_static')
# python26+
try:
ignore = shutil.ignore_patterns('.svn')
shutil.copytree(filepath, targetpath, ignore=ignore)
# python25-
except AttributeError:
shutil.copytree(filepath, targetpath)
continue
# include sub-documents that contain index.wiki
elif ( os.path.isdir(filepath) and \
os.path.exists(os.path.join(filepath, 'index.wiki')) ):
base_name = os.path.normpath(path).split(os.path.sep)[-1]
title = text.capitalizeWords(base_name)
newtarget = os.path.join(target, entry)
newcrumb = crumb_templ % {
'url': '%s/index.html',
'text': main_title
}
newcrumbs = breadcrumbs[:] + [newcrumb]
entry_title = text.capitalizeWords(entry)
opts = (basepath, entry, entry_title)
entry_item = '<a href="%s/%s/index.html">%s</a>' % opts
entry_contents.append(entry_item)
generateUserDocs(filepath, newtarget, page, newcrumbs, basepath)
# generate the main index file
indexfilename = os.path.join(target, 'index.html')
base_name = os.path.normpath(path).split(os.path.sep)[-1]
# generate the entry html
entry_html = ['<ul class=entries>']
for entry in entry_contents:
entry_html.append('<li>%s</li>' % entry)
entry_html.append('</ul>')
# base crumbs
crumbs = []
count = len(breadcrumbs)
for i, crumb in enumerate(breadcrumbs):
crumbs.append(crumb % (basepath + '/..' * count))
url_handler.setRootUrl(basepath + '/..' * count)
# add the parent crumb
crumb = crumb_templ % {'url': '#', 'text': main_title}
crumbs.append(crumb)
# generate the environ
environ = ENVIRON.copy()
environ['title'] = main_title
environ['base_url'] = base_url
environ['static_url'] = static_url
environ['breadcrumbs'] = ''.join(crumbs)
environ['sub_pages'] = ''.join(entry_html)
environ['navigation'] %= environ
# include a base template
if (not has_index_file):
wiki_templ = templates.template('userguide.html')
else:
f = open(os.path.join(path, 'index.wiki'), 'r')
wiki_txt = f.read()
f.close()
options = RENDER_OPTIONS.copy()
options['FILENAME'] = indexfilename
options['ROOT'] = base_url
wiki_templ = wikitext.render(wiki_txt, url_handler, options=options)
# generate the contents
environ['contents'] = wiki_templ % environ
html = page % environ
# generate the index HTML
index_file = open(indexfilename, 'w')
index_file.write(html)
index_file.close()
def init_environ( module, config ):
"""
Initializes the global environ with the given config module. If the given
module is None, then the default_config will be used.
:param module | <module>
:param config | <module> || None
"""
if ( not config ):
config = default_config
#---------------------------------------------------------------------------
# genrate module information
try:
module_title = config.MODULE_TITLE
except AttributeError:
module_title = module.__name__
try:
module_version = config.MODULE_VERSION
except AttributeError:
try:
module_version = module.__version__
except AttributeError:
module_version = '0.0.0'
#---------------------------------------------------------------------------
# generate copyright information
copyright = []
try:
show_docgen_link = config.SHOW_DOCGEN_LINK
except AttributeError:
show_docgen_link = True
if ( show_docgen_link ):
link = projex.website()
copyright.append('generated by <a href="%s">docgen</a>' % link)
try:
title = config.COMPANY_TITLE
except AttributeError:
title = 'Projex Software, LLC'
try:
url = config.COMPANY_URL
except AttributeError:
url = projex.website()
year = datetime.date.today().year
opts = (year, url, title)
copyright.append('copyright © %i <a href="%s">%s</a>' % opts)
#---------------------------------------------------------------------------
# grab the theme information
try:
theme = config.THEME
except AttributeError:
theme = 'base'
try:
theme_path = config.THEME_PATH
except AttributeError:
theme_path = ''
#---------------------------------------------------------------------------
# generate the title bar links
try:
links = config.NAVIGATION_LINKS
except AttributeError:
links = []
templ = templates.template('link_navigation.html')
navigation_links = []
for title, url in links:
navigation_links.append(templ % {'title': title, 'url': url})
#---------------------------------------------------------------------------
ENVIRON.clear()
ENVIRON['navigation'] = ''.join(navigation_links)
ENVIRON['copyright'] = ' '.join(copyright)
ENVIRON['module_title'] = module_title
ENVIRON['module_version'] = module_version
templates.setTheme(theme)
def breadcrumbs(self,
relativeTo = None,
first = True,
includeSelf = False):
"""
Creates a link to all of the previous modules for this item.
:param relativeTo | <Document> | Relative to another document.
first | <bool>
includeSelf | <bool> | Create a link to this doc.
:return <str>
"""
basecrumbs = ''
if ( not relativeTo ):
relativeTo = self
basecrumbs = self.title().split('.')[-1]
if ( includeSelf ):
opts = {
'url': './' + os.path.split(self.url())[1],
'text': self.title().split('.')[-1]
}
basecrumbs = templates.template('link_breadcrumbs.html') % opts
if ( inspect.isclass( self._object ) ):
doc = Document.cache.get( self._object.__module__ )
elif ( inspect.ismodule( self._object ) ):
parent_mod = '.'.join( self._object.__name__.split('.')[:-1] )
doc = Document.cache.get( parent_mod )
else:
doc = None
if ( doc ):
opts = {}
opts['url'] = doc.url(relativeTo)
opts['text' ] = doc.title().split('.')[-1]
link = templates.template('link_breadcrumbs.html') % opts
subcrumbs = doc.breadcrumbs(relativeTo, first = False)
else:
subcrumbs = ''
link = ''
parts = []
if ( first ):
# add the home url
baseurl = self.baseurl()
home_url = '%s/index.html' % baseurl
home_opts = { 'text': 'Home', 'url': home_url }
home_part = templates.template('link_breadcrumbs.html') % home_opts
parts.append(home_part)
# add the api url
api_url = '%s/api/index.html' % baseurl
api_opts = { 'text': 'API', 'url': api_url }
api_part = templates.template('link_breadcrumbs.html') % api_opts
parts.append(api_part)
if ( subcrumbs ):
parts.append( subcrumbs )
if ( link ):
parts.append( link )
if ( basecrumbs ):
parts.append( basecrumbs )
return ''.join( parts )
def generateFunctionDocs(outpath, page, basemod):
"""
Generates the module index html document based on the currently loaded
module documents.
"""
from projex.docgen.document import Document
functions = {}
for doc in Document.cache.values():
obj = doc.object()
if ( inspect.ismodule(obj) and
not obj.__name__.startswith(basemod) ):
continue
elif ( inspect.isclass(obj) and
not obj.__module__.startswith(basemod) ):
continue
for data in doc.data().values():
if ( 'function' in data.dataType ):
first = data.name.strip('_')[0].upper()
functions.setdefault(first, [])
functions[first].append((doc, data))
elif ( 'method' in data.dataType ):
first = data.name.strip('_')[0].upper()
functions.setdefault(first, [])
functions[first].append((doc, data))
function_html = []
letters = []
keys = functions.keys()
keys.sort()
for key in keys:
docs = functions[key]
docs.sort( lambda x, y: cmp( x[1].name, y[1].name ) )
contents = []
for doc, data in docs:
opts = {}
opts['class'] = doc.title()
opts['text'] = data.name
opts['url'] = './%s#%s' % (doc.url(), data.name)
contents.append( templates.template('link_function.html') % opts )
letter_opts = {}
letter_opts['text'] = key
letter_opts['url'] = '#%s' % key
letters.append( templates.template('link_standard.html') % letter_opts )
functions_opts = {}
functions_opts['letter'] = key
functions_opts['contents'] = '' + '<br/>'.join(contents)
function_text = templates.template('letter_group.html') % functions_opts
function_html.append( function_text )
cls_data = {}
cls_data['contents'] = '\n'.join(function_html)
cls_data['letters'] = ' . '.join(letters)
cls_html = templates.template('functions.html') % cls_data
functions_opt = ENVIRON.copy()
functions_opt['title'] = 'API Functions'
functions_opt['base_url'] = '..'
functions_opt['static_url'] = '../_static'
functions_opt['contents'] = cls_html
functions_opt['navigation'] %= functions_opt
functions_opt['breadcrumbs'] = breadcrumbs([('../index.html', 'Home'),
('./index.html', 'API'),
('', 'All Functions')])
html = page % functions_opt
functionsfile = open(os.path.join(outpath, 'api/functions.html'), 'w')
functionsfile.write(html)
functionsfile.close()
def generate(module,
outputpath='./resources/docs/html',
userpath='',
config=None):
"""
Generates documenation for the inputed filepath at the given output \
location. The system can also supply the root location for user \
documentation that can be included in addition to the code by supplying \
a root userdocs path.
:param module | <module> || <str>
:param outputpath | <str>
:param config | <module> || None
:return <bool> success
"""
from projex.docgen.document import Document
if (type(module) == str):
# extract from a specific filepath
if (os.path.exists(module)):
package = projex.packageFromPath(module)
if (not package):
msg = '%s is an invalid module.' % module
raise errors.DocumentationError(msg)
root_path = projex.packageRootPath(module)
sys.path.insert(0, root_path)
# otherwise, use it as the package name
else:
projex.requires(module)
package = module.split('-')[0]
try:
__import__(package)
module = sys.modules[package]
except ImportError:
msg = 'Could not import the %s module' % package
raise errors.DocumentationError(msg)
except KeyError:
msg = 'Could not import the %s module' % package
raise errors.DocumentationError(msg)
# initialize the global environ
if (config is None):
config = default_config
init_environ(module, config)
logger.info('Generating module documentation %s...' % module.__name__)
# load the base page and style information
page = templates.template('page.html')
# start generating the documents
Document.cache.clear()
# generate the module documentation
try:
ignore = config.IGNORE
except AttributeError:
ignore = None
doc = generateModuleDocument(module, ignore=ignore)
modpath = os.path.dirname(module.__file__)
outpath = outputpath.replace('./', modpath + '/')
# clear the docs path
if (os.path.exists(outpath)):
shutil.rmtree(outpath)
if (not os.path.exists(outpath)):
logger.info('Making doc path: ' + outpath)
os.makedirs(outpath)
# make the root api documentation
api_path = outpath.rstrip('/') + '/api/'
if not os.path.exists(api_path):
logger.info('Making doc path:' + api_path)
os.mkdir(api_path)
# generate the api docs
doc.export(api_path, page=page)
# generate the all classes page
generateClassDocs(outpath, page, module.__name__)
generateModuleDocs(outpath, page, module.__name__)
generateFunctionDocs(outpath, page, module.__name__)
generateApiIndex(outpath, page)
generateDocumentIndex(outpath, page)
# create the user docs
if (userpath):
userdocs = os.path.abspath(userpath)
elif (config != default_config):
userdocs = os.path.dirname(config.__file__)
else:
userdocs = os.path.abspath('./docs')
if (os.path.exists(userdocs)):
targetuserdocs = outpath
templ = templates.template('link_breadcrumbs.html')
generateUserDocs(userdocs, targetuserdocs, page)
# copy the syntaxhighlighter code
targetpath = os.path.join(outpath, '_static')
paths = []
paths.append(resources.find('ext/prettify'))
paths.append(templates.path('javascript'))
paths.append(templates.path('css'))
paths.append(templates.path('images'))
paths.append(templates.path('img'))
logger.info('Copying static resources...')
# python26+
try:
ignore = shutil.ignore_patterns('.svn')
except AttributeError:
ignore = None
for path in paths:
if (not os.path.exists(path)):
continue
basename = os.path.basename(path)
instpath = os.path.join(targetpath, basename)
if (ignore is not None):
shutil.copytree(path, instpath, ignore=ignore)
else:
shutil.copytree(path, instpath)
# create a compressed xdk file
logger.info('Creating XDK file...')
zfilename = os.path.join(outpath, '../%s.xdk' % module.__name__)
zfilename = os.path.abspath(zfilename)
generateXdk(outpath, zfilename)
def render(self,
title,
contents,
breadcrumbs=None,
baseUrl=None,
staticUrl=None,
filepath='',
includeTitleInCrumbs=False,
debug=False):
"""
Renders the inputed text to HTML for this dox, including the
inputed breadcrumbs when desired.
:param title | <str>
contents | <DoxSource.Type>
breadcrumbs | [<str>, ..] || None
:return <str>
"""
self.initEnviron()
curdir = os.curdir
if self.filename():
os.chdir(os.path.dirname(self.filename()))
# generate temp breadcrumbs
offset = 1
if breadcrumbs is None:
filepath = str(filepath)
breadcrumbs = []
dir_name = os.path.dirname(filepath)
fname = os.path.basename(filepath).split('.')[0]
if fname.lower() != 'index':
breadcrumbs.append(projex.text.pretty(fname))
offset = 2
index_file = os.path.abspath(
os.path.join(dir_name, '../index.wiki'))
while os.path.exists(index_file):
crumb = os.path.normpath(dir_name).split(os.path.sep)[-1]
dir_name = os.path.abspath(os.path.join(dir_name, '..'))
breadcrumbs.append(projex.text.pretty(crumb))
index_file = os.path.abspath(
os.path.join(dir_name, '../index.wiki'))
breadcrumbs.append('Home')
breadcrumbs.reverse()
count = len(breadcrumbs) - offset
if baseUrl is None:
baseUrl = '.' + '/..' * count
if staticUrl is None:
staticUrl = baseUrl + '/_static'
page_templ = templates.template('page.html')
crumb_templ = templates.template('link_breadcrumbs.html')
nav_templ = templates.template('link_navigation.html')
# extract the mako template information
templatePaths = self.templatePaths()
rem_paths = []
for path in templatePaths:
if not path in sys.path:
sys.path.insert(0, path)
rem_paths.append(path)
options = commands.RENDER_OPTIONS.copy()
options['FILENAME'] = filepath
options['ROOT'] = baseUrl
if debug:
dir_name = os.path.dirname(filepath)
url = os.path.abspath(dir_name + baseUrl + '/../resources')
commands.url_handler.setReplaceWikiSuffix(False)
commands.url_handler.setStaticUrl('file:///' + url)
else:
commands.url_handler.setStaticUrl(baseUrl + '/_static')
contents = projex.wikitext.render(contents,
commands.url_handler,
options=options,
templatePaths=templatePaths)
if debug:
commands.url_handler.setStaticUrl(None)
commands.url_handler.setReplaceWikiSuffix(True)
# generate the breadcrumb links
crumbs = []
for i, crumb in enumerate(breadcrumbs):
url = '.' + '/..' * (count - i) + '/index.html'
opts = {'text': crumb, 'url': url}
crumbs.append(crumb_templ % opts)
if includeTitleInCrumbs:
crumbs.append(crumb_templ % {'text': title, 'url': ''})
# generate the environ data
environ = commands.ENVIRON.copy()
environ['base_url'] = baseUrl
environ['static_url'] = staticUrl
environ['title'] = title
environ['contents'] = contents
environ['breadcrumbs'] = ''.join(crumbs)
environ['module_title'] = self.title()
environ['module_version'] = self.version()
environ['copyright'] = self.copyright()
# create navigation links
nav = []
for title, url in self.navigation():
href = url % environ
nav.append(nav_templ % {'title': title, 'url': href})
environ['navigation'] = ''.join(nav)
os.chdir(curdir)
# generate the html
result = page_templ % environ
sys.path = sys.path[len(rem_paths):]
return result
def _generateMemberDocs( self, title, data ):
"""
Generates the member documentation for the inputed set of data.
:param title | <str>
:param data | [ <DocumentData>, .. ]
"""
if ( not data ):
return ''
bases = []
subclasses = []
# generate the html
html = []
data.sort(lambda x, y: cmp(x.name, y.name))
for entry in data:
# generate function information
if ( 'function' in entry.dataType or 'method' in entry.dataType ):
# lookup base methods for reimplimintation
reimpliments = []
for base in bases:
if ( entry.name in base.__dict__ ):
doc = commands.findDocument(base)
if ( doc ):
opt = {}
opt['text'] = base.__name__
opt['url'] = doc.url( relativeTo = self )
opt['url'] += '#' + entry.name
href = templates.template('link_standard.html') % opt
reimpliments.append( href )
else:
reimpliments.append( entry.name )
reimpliment_doc = ''
if ( reimpliments ):
urls = ','.join(reimpliments)
reimpliment_doc = 'Reimpliments from %s.' % urls
# lookup submodules for reimplimentation
reimplimented = []
for subcls in subclasses:
if ( entry.name in subcls.__dict__ ):
doc = commands.findDocument(subcls)
if ( doc ):
opt = {}
opt['text'] = subcls.__name__
opt['url'] = doc.url( relativeTo = self )
opt['url'] += '#' + entry.name
href = templates.template('link_standard.html') % opt
reimplimented.append( href )
else:
reimplimented.append( entry.name )
reimplimented_doc = ''
if ( reimplimented ):
urls = ','.join(reimplimented)
reimplimented_doc = 'Reimplimented by %s.' % urls
func_split = entry.dataType.split(' ')
desc = ''
if ( len(func_split) > 1 ):
desc = '[%s]' % func_split[0]
# add the function to the documentation
environ = commands.ENVIRON.copy()
environ['type'] = entry.dataType
environ['name'] = entry.name
environ['args'] = self._generateArgs( entry.value )
environ['desc'] = desc
environ['contents'] = self._generateObjectDocs(entry.value)
environ['reimpliments'] = reimpliment_doc
environ['reimplimented'] = reimplimented_doc
html.append( templates.template('docs_function.html') % environ )
elif ( entry.dataType == 'enum' ):
environ = commands.ENVIRON.copy()
environ['name'] = entry.name
value_contents = []
values = entry.value.values()
values.sort()
for value in values:
value_opts = {}
value_opts['key'] = entry.value[value]
value_opts['value'] = value
value_templ = templates.template('docs_enum_value.html')
value_item = value_templ % value_opts
value_contents.append( value_item )
environ['contents'] = '\n'.join(value_contents)
html.append( templates.template('docs_enum.html') % environ )
environ = {}
environ['title'] = title
environ['contents'] = '\n'.join( html )
return templates.template('docs_members.html') % environ
def generate( module,
outputpath = './resources/docs/html',
userpath = '',
config = None ):
"""
Generates documenation for the inputed filepath at the given output \
location. The system can also supply the root location for user \
documentation that can be included in addition to the code by supplying \
a root userdocs path.
:param module | <module> || <str>
:param outputpath | <str>
:param config | <module> || None
:return <bool> success
"""
from projex.docgen.document import Document
if ( type(module) == str ):
# extract from a specific filepath
if ( os.path.exists(module) ):
package = projex.packageFromPath(module)
if ( not package ):
msg = '%s is an invalid module.' % module
raise errors.DocumentationError(msg)
root_path = projex.packageRootPath(module)
sys.path.insert(0, root_path)
# otherwise, use it as the package name
else:
projex.requires(module)
package = module.split('-')[0]
try:
__import__(package)
module = sys.modules[package]
except ImportError:
msg = 'Could not import the %s module' % package
raise errors.DocumentationError(msg)
except KeyError:
msg = 'Could not import the %s module' % package
raise errors.DocumentationError(msg)
# initialize the global environ
if ( config is None ):
config = default_config
init_environ(module, config)
logger.info('Generating module documentation %s...' % module.__name__)
# load the base page and style information
page = templates.template('page.html')
# start generating the documents
Document.cache.clear()
# generate the module documentation
try:
ignore = config.IGNORE
except AttributeError:
ignore = None
doc = generateModuleDocument(module, ignore = ignore)
modpath = os.path.dirname(module.__file__)
outpath = outputpath.replace( './', modpath + '/' )
# clear the docs path
if ( os.path.exists( outpath ) ):
shutil.rmtree( outpath )
if ( not os.path.exists( outpath ) ):
logger.info( 'Making doc path: ' + outpath )
os.makedirs(outpath)
# make the root api documentation
api_path = outpath.rstrip('/') + '/api/'
if not os.path.exists(api_path):
logger.info( 'Making doc path:' + api_path )
os.mkdir(api_path)
# generate the api docs
doc.export(api_path, page = page)
# generate the all classes page
generateClassDocs( outpath, page, module.__name__ )
generateModuleDocs( outpath, page, module.__name__)
generateFunctionDocs( outpath, page, module.__name__)
generateApiIndex( outpath, page )
generateDocumentIndex( outpath, page)
# create the user docs
if ( userpath ):
userdocs = os.path.abspath(userpath)
elif ( config != default_config ):
userdocs = os.path.dirname(config.__file__)
else:
userdocs = os.path.abspath('./docs')
if ( os.path.exists(userdocs) ):
targetuserdocs = outpath
templ = templates.template('link_breadcrumbs.html')
generateUserDocs( userdocs, targetuserdocs, page )
# copy the syntaxhighlighter code
targetpath = os.path.join(outpath,'_static')
paths = []
paths.append(resources.find('ext/prettify'))
paths.append(templates.path('javascript'))
paths.append(templates.path('css'))
paths.append(templates.path('images'))
paths.append(templates.path('img'))
logger.info('Copying static resources...')
# python26+
try:
ignore = shutil.ignore_patterns('.svn')
except AttributeError:
ignore = None
for path in paths:
if ( not os.path.exists(path) ):
continue
basename = os.path.basename(path)
instpath = os.path.join(targetpath, basename)
if ( ignore is not None ):
shutil.copytree( path, instpath, ignore = ignore )
else:
shutil.copytree(path, instpath)
# create a compressed xdk file
logger.info('Creating XDK file...')
zfilename = os.path.join(outpath, '../%s.xdk' % module.__name__)
zfilename = os.path.abspath(zfilename)
generateXdk(outpath, zfilename)
def generateUserDocs(path,
target,
page=None,
breadcrumbs=None,
basepath='.',
title=''):
"""
Generates the user documentation for the inputed path by \
rendering any wiki text files to html and saving it out to the doc \
root.
:param path | <str>
target | <str>
page | <str>
source | <str>
breadcrumbs | [<str>, .. ] || None
"""
logger.info('Generating user documentation...')
if page is None:
page = templates.template('page.html')
if not os.path.exists(target):
os.mkdir(target)
if breadcrumbs == None:
breadcrumbs = []
crumb_templ = templates.template('link_breadcrumbs.html')
# setup the base crumbs
base_url = basepath + '/..' * len(breadcrumbs)
static_url = base_url + '/_static'
url_handler.setRootUrl(base_url)
# setup the title
if not title:
main_title = 'Home'
if breadcrumbs:
main_title = os.path.normpath(path).split(os.path.sep)[-1]
main_title = text.pretty(main_title)
else:
main_title = title
entry_contents = []
has_index_file = False
for entry in sorted(os.listdir(path)):
filepath = os.path.join(path, entry)
# skip the svn information
if ( entry == '.svn' ):
continue
# check for manual index overrides
elif ( entry == 'index.wiki' ):
has_index_file = True
# add wiki pages to the system
elif ( entry.endswith('.wiki') ):
filename = os.path.join(path, entry)
outfilename = os.path.join(target, entry.replace('.wiki','.html'))
wiki_file = open(filename, 'r')
wiki_contents = wiki_file.read()
wiki_file.close()
crumbs = []
count = len(breadcrumbs)
for i, crumb in enumerate(breadcrumbs):
crumbs.append(crumb % (basepath + '/..' * count))
# add the base crumb
crumb = crumb_templ % {'url': '%s/index.html' % basepath,
'text': main_title}
crumbs.append(crumb)
# add the page crumb
crumb = crumb_templ % {'url': '#', 'text': title}
crumbs.append( crumb )
crumbstr = ''.join(crumbs)
# generate the contents
title = text.capitalizeWords(entry.split('.')[0])
options = RENDER_OPTIONS.copy()
options['FILENAME'] = filepath
options['ROOT'] = base_url
contents = wikitext.render(wiki_contents,
url_handler,
options=options)
# update the environ
environ = ENVIRON.copy()
environ['title'] = title
environ['contents'] = contents
environ['base_url'] = base_url
environ['static_url'] = static_url
environ['breadcrumbs'] = crumbstr
environ['navigation'] %= environ
url = entry.replace('.wiki', '.html')
entry_item = '<a href="%s/%s">%s</a>' % (basepath, url, title)
entry_contents.append( entry_item )
html = page % environ
html_file = open(outfilename, 'w')
html_file.write(html)
html_file.close()
continue
# copy static paths
elif ( entry == '_static' ):
targetpath = os.path.join(target, '_static')
# python26+
try:
ignore = shutil.ignore_patterns('.svn')
shutil.copytree(filepath, targetpath, ignore=ignore)
# python25-
except AttributeError:
shutil.copytree(filepath, targetpath)
continue
# include sub-documents that contain index.wiki
elif ( os.path.isdir(filepath) and \
os.path.exists(os.path.join(filepath, 'index.wiki')) ):
base_name = os.path.normpath(path).split(os.path.sep)[-1]
title = text.capitalizeWords(base_name)
newtarget = os.path.join(target, entry)
newcrumb = crumb_templ % {'url': '%s/index.html',
'text': main_title}
newcrumbs = breadcrumbs[:] + [newcrumb]
entry_title = text.capitalizeWords(entry)
opts = (basepath, entry, entry_title)
entry_item = '<a href="%s/%s/index.html">%s</a>' % opts
entry_contents.append( entry_item )
generateUserDocs(filepath, newtarget, page, newcrumbs, basepath)
# generate the main index file
indexfilename = os.path.join(target, 'index.html')
base_name = os.path.normpath(path).split(os.path.sep)[-1]
# generate the entry html
entry_html = ['<ul class=entries>']
for entry in entry_contents:
entry_html.append('<li>%s</li>' % entry)
entry_html.append('</ul>')
# base crumbs
crumbs = []
count = len(breadcrumbs)
for i, crumb in enumerate(breadcrumbs):
crumbs.append(crumb % (basepath + '/..' * count))
url_handler.setRootUrl(basepath + '/..' * count)
# add the parent crumb
crumb = crumb_templ % {'url': '#', 'text': main_title}
crumbs.append(crumb)
# generate the environ
environ = ENVIRON.copy()
environ['title'] = main_title
environ['base_url'] = base_url
environ['static_url'] = static_url
environ['breadcrumbs'] = ''.join(crumbs)
environ['sub_pages'] = ''.join(entry_html)
environ['navigation'] %= environ
# include a base template
if ( not has_index_file ):
wiki_templ = templates.template('userguide.html')
else:
f = open(os.path.join(path, 'index.wiki'), 'r')
wiki_txt = f.read()
f.close()
options = RENDER_OPTIONS.copy()
options['FILENAME'] = indexfilename
options['ROOT'] = base_url
wiki_templ = wikitext.render(wiki_txt,
url_handler,
options=options)
# generate the contents
environ['contents'] = wiki_templ % environ
html = page % environ
# generate the index HTML
index_file = open(indexfilename, 'w')
index_file.write(html)
def _generateSummary( self, section, values, columns = 1 ):
"""
Generates summary information for the inputed section and value
data.
:param section | <str>
:param values | [ <DocumentData>, .. ]
:param columns | <int>
:return <str>
"""
# strip out built-in variables
newvalues = []
for value in values:
if ( not (value.privacy == 'built-in' and
value.dataType == 'variable' )):
newvalues.append(value)
values = newvalues
if ( not values ):
return ''
# split the data into columns
values.sort( lambda x, y: cmp( x.name.lower(), y.name.lower() ) )
url = self.url()
coldata = []
if ( columns > 1 ):
pass
else:
coldata = [values]
html = []
processed = []
for colitem in coldata:
for data in colitem:
data_environ = {}
data_environ['url'] = url
data_environ['name'] = data.name
data_environ['type'] = data.dataType
processed.append( data.name )
if ( 'function' in data.dataType or
'method' in data.dataType ):
data_environ['args'] = self._generateArgs( data.value )
templ = templates.template('summary_function.html')
html.append( templ % data_environ )
elif ( data.dataType == 'enum' ):
templ = templates.template('summary_enum.html')
html.append( templ % data_environ )
elif ( 'variable' in data.dataType or
'member' in data.dataType ):
try:
value = getattr(self._object, data.name)
except AttributeError:
value = None
data_environ['value_type'] = type(value).__name__
templ = templates.template('summary_variable.html')
html.append( templ % data_environ )
else:
datadoc = commands.findDocument(data.value)
if ( datadoc ):
opts = {}
opts['text'] = data.name
opts['url'] = datadoc.url( relativeTo = self )
contents = templates.template('link_standard.html') % opts
else:
contents = data.name
data_environ['contents'] = contents
templ = templates.template('summary_item.html')
html.append( templ % data_environ )
# update the bases environ
members = self._collectMembers(self._object)
inherited_members = {}
for member in members:
mem_name = member.name
mem_kind = member.kind
mem_cls = member.defining_class
mem_value = member.object
if ( hasattr(member.object, 'func_type') ):
mem_kind = member.object.func_type
if ( mem_cls == self._object ):
continue
data = DocumentData.create( mem_name,
mem_value,
mem_kind,
'member',
'method' )
if ( section != data.section() ):
continue
inherited_members.setdefault( mem_cls, 0 )
inherited_members[mem_cls] += 1
inherit_summaries = []
templ = templates.template('summary_inherit.html')
bases = self._bases( self._object, True )
inherits = inherited_members.keys()
inherits.sort( lambda x, y: cmp( bases.index(x), bases.index(y) ) )
for inherited in inherits:
count = inherited_members[inherited]
doc = commands.findDocument( inherited )
if ( not doc ):
continue
opt = {}
opt['count'] = count
opt['base'] = inherited.__name__
opt['url'] = doc.url( relativeTo = self )
opt['type'] = section
inherit_summaries.append( templ % opt )
# generate the summary information
words = [word.capitalize() for word in text.words(section)]
words[-1] = text.pluralize(words[-1])
summary_environ = {}
summary_environ['contents'] = '\n'.join(html)
summary_environ['section'] = ' '.join(words)
summary_environ['inherits'] = '\n'.join(inherit_summaries)
return templates.template('summary.html') % summary_environ
def generateModuleDocs(outpath, page, basemod):
"""
Generates the module index html document based on the currently loaded
module documents.
"""
from projex.docgen.document import Document
modules = {}
for doc in Document.cache.values():
obj = doc.object()
if (inspect.ismodule(obj) and obj.__name__.startswith(basemod)):
first = obj.__name__.split('.')[-1][0].upper()
modules.setdefault(first, [])
modules[first].append(doc)
module_html = []
letters = []
keys = modules.keys()
keys.sort()
for key in keys:
docs = modules[key]
docs.sort(lambda x, y: cmp(x.title(), y.title()))
contents = []
for doc in docs:
opts = {}
opts['text'] = doc.title()
opts['url'] = './' + doc.url()
contents.append(templates.template('link_standard.html') % opts)
letter_opts = {}
letter_opts['text'] = key
letter_opts['url'] = '#%s' % key
letters.append(templates.template('link_standard.html') % letter_opts)
modules_opts = {}
modules_opts['letter'] = key
modules_opts['contents'] = '' + '<br/>'.join(contents)
module_text = templates.template('letter_group.html') % modules_opts
module_html.append(module_text)
cls_data = ENVIRON.copy()
cls_data['base_url'] = '..'
cls_data['static_url'] = '../_static'
cls_data['contents'] = '\n'.join(module_html)
cls_data['letters'] = ' . '.join(letters)
cls_data['navigation'] %= cls_data
cls_html = templates.template('modules.html') % cls_data
modules_opt = ENVIRON.copy()
modules_opt['title'] = 'API Modules'
modules_opt['base_url'] = '..'
modules_opt['static_url'] = '../_static'
modules_opt['contents'] = cls_html
modules_opt['navigation'] %= modules_opt
modules_opt['breadcrumbs'] = breadcrumbs([('../index.html', 'Home'),
('./index.html', 'API'),
('', 'All Modules')])
html = page % modules_opt
modulesfile = open(os.path.join(outpath, 'api/modules.html'), 'w')
modulesfile.write(html)
modulesfile.close()
def export( self, basepath, page = None ):
"""
Exports the html files for this document and its children to the
given basepath.
:param basepath | <str>
:param page | <str> || None
:return <bool> success
"""
# make sure the base path exists
if ( not os.path.exists( basepath ) ):
return False
basepath = os.path.normpath(basepath)
url = self.url()
filename = os.path.join(basepath, url)
docpath = os.path.dirname(filename)
# add the doc path
if ( not os.path.exists(docpath) ):
os.makedirs(docpath)
if ( not page ):
page = templates.template('page.html')
# setup the default environ
commands.url_handler.setRootUrl(self.baseurl())
doc_environ = commands.ENVIRON.copy()
doc_environ['title'] = self.title()
doc_environ['base_url'] = self.baseurl()
doc_environ['static_url'] = doc_environ['base_url'] + '/_static'
doc_environ['contents'] = self.html()
doc_environ['breadcrumbs'] = self.breadcrumbs(includeSelf = True)
doc_environ['navigation'] %= doc_environ
# generate the main html file
exportfile = open(filename, 'w')
exportfile.write( page % doc_environ )
exportfile.close()
# generate the all members html file
allmember_html = self.allMembersHtml()
if ( allmember_html ):
fpath, fname = os.path.split(filename)
fname = fname.split('.')[0] + '-allmembers.html'
afilesource = os.path.join(fpath, fname)
doc_environ['contents'] = allmember_html
# create the crumbs
crumbs = self.breadcrumbs(includeSelf = True)
opts = {'url': '#', 'text': 'All Members'}
crumbs += templates.template('link_breadcrumbs.html') % opts
doc_environ['breadcrumbs'] = crumbs
# save the all members file
membersfile = open(afilesource, 'w')
membersfile.write( page % doc_environ )
membersfile.close()
# generate the source code file
source_html = self.sourceHtml()
if ( source_html ):
fpath, fname = os.path.split(filename)
fname = fname.split('.')[0] + '-source.html'
sfilesource = os.path.join(fpath, fname)
doc_environ['contents'] = source_html
# create the crumbs
crumbs = self.breadcrumbs(includeSelf = True)
opts = {'url': '#', 'text': 'Source Code'}
crumbs += templates.template('link_breadcrumbs.html') % opts
doc_environ['breadcrumbs'] = crumbs
# save the source file
sourcefile = open(sfilesource, 'w')
sourcefile.write( page % doc_environ )
sourcefile.close()
# generate the children
for child in self.children():
child.export(basepath, page)
def generateFunctionDocs(outpath, page, basemod):
"""
Generates the module index html document based on the currently loaded
module documents.
"""
from projex.docgen.document import Document
functions = {}
for doc in Document.cache.values():
obj = doc.object()
if (inspect.ismodule(obj) and not obj.__name__.startswith(basemod)):
continue
elif (inspect.isclass(obj) and not obj.__module__.startswith(basemod)):
continue
for data in doc.data().values():
if ('function' in data.dataType):
first = data.name.strip('_')[0].upper()
functions.setdefault(first, [])
functions[first].append((doc, data))
elif ('method' in data.dataType):
first = data.name.strip('_')[0].upper()
functions.setdefault(first, [])
functions[first].append((doc, data))
function_html = []
letters = []
keys = functions.keys()
keys.sort()
for key in keys:
docs = functions[key]
docs.sort(lambda x, y: cmp(x[1].name, y[1].name))
contents = []
for doc, data in docs:
opts = {}
opts['class'] = doc.title()
opts['text'] = data.name
opts['url'] = './%s#%s' % (doc.url(), data.name)
contents.append(templates.template('link_function.html') % opts)
letter_opts = {}
letter_opts['text'] = key
letter_opts['url'] = '#%s' % key
letters.append(templates.template('link_standard.html') % letter_opts)
functions_opts = {}
functions_opts['letter'] = key
functions_opts['contents'] = '' + '<br/>'.join(contents)
function_text = templates.template(
'letter_group.html') % functions_opts
function_html.append(function_text)
cls_data = {}
cls_data['contents'] = '\n'.join(function_html)
cls_data['letters'] = ' . '.join(letters)
cls_html = templates.template('functions.html') % cls_data
functions_opt = ENVIRON.copy()
functions_opt['title'] = 'API Functions'
functions_opt['base_url'] = '..'
functions_opt['static_url'] = '../_static'
functions_opt['contents'] = cls_html
functions_opt['navigation'] %= functions_opt
functions_opt['breadcrumbs'] = breadcrumbs([('../index.html', 'Home'),
('./index.html', 'API'),
('', 'All Functions')])
html = page % functions_opt
functionsfile = open(os.path.join(outpath, 'api/functions.html'), 'w')
functionsfile.write(html)
functionsfile.close()
