Prior to a mass rename of the RST sources and utilities.
sphinx-build source_dir destination_dir
-where
+where
source_dir is the source directory which includes configuration file conf.py and all source files;
destination_dir is the directory for the built documentation.
krb5_int32.rst
krb5_kdc_rep.rst
krb5_kdc_req.rst
- krb5_keyblock.rst
+ krb5_keyblock.rst
krb5_keytab_entry.rst
krb5_keyusage.rst
krb5_kt_cursor.rst
krb5_timestamp.rst
krb5_tkt_authent.rst
krb5_trace_callback.rst
- krb5_trace_info.rst
+ krb5_trace_info.rst
krb5_transited.rst
krb5_typed_data.rst
krb5_ui_4.rst
access to the backup data is secured as tightly as access to the
master password itself.
-.. note:: If you choose not to install a stash file, the KDC will prompt you for the master key each time it starts up.
+.. note:: If you choose not to install a stash file, the KDC will prompt you for the master key each time it starts up.
This means that the KDC will not be able to start automatically, such as after a system reboot.
other location mechanisms determine the server addresses, or another
code if it experienced a failure which should abort the location
process.
-
+
A module can create and destroy per-library-context state objects by
implementing the **init** and **fini** methods. State objects have
the type void \*, and should be cast to an internal type for the state
self.short_description = argkw.get('short_description')
self.long_description = argkw.get('long_description')
self.version = argkw.get('version')
-
+
def __repr__(self):
result = list()
for (attr,value) in self.__dict__.iteritems():
result.append('%s=%s' % (attr,value))
return 'Attribute: %s' % ','.join(result)
-
+
class CompositeType():
def __init__(self, **argkw):
self.friends = argkw.get('friends')
self.type = argkw.get('type')
self.attributes = self._setAttributes(argkw.get('attributes'))
-
+
def __repr__(self):
result = list()
for (attr,value) in self.__dict__.iteritems():
if value is not None:
attributes = ['%s' % a for a in value]
value = '\n %s' % '\n '.join(attributes)
-
- result.append('%s: %s' % (attr,value))
+
+ result.append('%s: %s' % (attr,value))
result = '\n'.join(result)
-
+
return result
def _setAttributes(self, attributes):
result = list()
for a in attributes:
result.append(Attribute(**a))
-
+
return result
def struct_reference(self, name):
result = re.sub(r'_', '-', name)
result = '_%s-struct' % result
-
+
return result
def macro_reference(self, name):
result = re.sub(r'_', '-', name)
result = '_%s-data' % result
-
+
return result
class Parameter(object):
self.typeId = argkw.get('typeId')
self.description = argkw.get('description')
self.version = argkw.get('version')
-
+
def __repr__(self):
content = (self.name,self.direction,self.seqno,self.type,self.typeId,self.description)
return 'Parameter: name=%s,direction=%s,seqno=%s,type=%s,typeId=%s,descr=%s' % content
-
+
class Function(object):
def __init__(self, **argkw):
self.category = 'function'
self.long_description = argkw.get('long_description')
self.deprecated_description = argkw.get('deprecated_description')
self.friends = argkw.get('friends')
-
+
def _setParameters(self, parameters):
result = None
if parameters is not None:
result = list()
for p in parameters:
result.append(Parameter(**p))
-
+
return result
-
+
def getObjectRow(self):
- result = [str(self.Id),
+ result = [str(self.Id),
self.name,
self.category]
-
+
return ','.join(result)
-
+
def getObjectDescriptionRow(self):
- result = [self.Id,
- self.active,
- self.version,
+ result = [self.Id,
+ self.active,
+ self.version,
self.short_description,
self.long_description]
lines.append('Function return type description:\n%s' % self.return_description)
lines.append('Function retval description:\n%s' % self.retval_description)
lines.append('Function short description:\n%s' % self.short_description)
- lines.append('Function long description:\n%s' % self.long_description)
+ lines.append('Function long description:\n%s' % self.long_description)
lines.append('Warning description:\n%s' % self.warn_description)
lines.append('See also description:\n%s' % self.sa_description)
- lines.append('NOTE description:\n%s' % self.notes_description)
+ lines.append('NOTE description:\n%s' % self.notes_description)
lines.append('Version introduced:\n%s' % self.version_num)
lines.append('Deprecated description:\n%s' % self.deprecated_description)
result = '\n'.join(lines)
-
+
return result
self.function = Function(**argkw)
elif argkw['category'] == 'composite':
self.category = 'composite'
- self.composite = CompositeType(**argkw)
+ self.composite = CompositeType(**argkw)
def __repr__(self):
obj = getattr(self,self.category)
print type(obj)
return str(obj)
-
+
def signature(self):
param_list = list()
for p in self.function.parameters:
param_list = ', '.join(param_list)
result = '%s %s(%s)' % (self.function.return_type,
self.function.name, param_list)
-
+
return result
-
+
def save(self, path, template_path):
f = open(template_path, 'r')
t = Template(f.read(),self)
doc_path = '../docutil/example.yml'
argkw = yaml.load(open(doc_path,'r'))
super(DocModelTest,self).__init__(**argkw)
-
+
def run_tests(self):
self.test_save()
def test_print(self):
print 'testing'
print self
-
+
def test_save(self):
template_path = '../docutil/function2edit.html'
-
+
path = '/var/tsitkova/Sources/v10/trunk/documentation/test_doc.html'
- self.save(path, template_path)
-
+ self.save(path, template_path)
+
if __name__ == '__main__':
tester = DocModelTest()
tester.run_tests()
'''
Copyright 2011 by the Massachusetts
Institute of Technology. All Rights Reserved.
-
+
Export of this software from the United States of America may
require a specific license from the United States Government.
It is the responsibility of any person or organization contemplating
export to obtain such a license before exporting.
-
+
WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
distribute this software and its documentation for any purpose and
without fee is hereby granted, provided that the above copyright
if in_dir is None or out_dir is None:
parser.error("Input and output directories are required")
-
+
if action == "all" or action == "typedef":
tester = DoxyTypesTest(in_dir, out_dir)
tester.run_tests()
'''
Copyright 2011 by the Massachusetts
Institute of Technology. All Rights Reserved.
-
+
Export of this software from the United States of America may
require a specific license from the United States Government.
It is the responsibility of any person or organization contemplating
export to obtain such a license before exporting.
-
+
WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
distribute this software and its documentation for any purpose and
without fee is hereby granted, provided that the above copyright
import re
from collections import defaultdict
-from xml.sax import make_parser
+from xml.sax import make_parser
from xml.sax.handler import ContentHandler
from docmodel import *
"""
@param node: name - the name of a node.
@param attributes: a dictionary populated with attributes of a node
- @param children: a dictionary with lists of children nodes. Nodes
+ @param children: a dictionary with lists of children nodes. Nodes
in lists are ordered as they appear in a document.
- @param content: a content of xml node represented as a list of
+ @param content: a content of xml node represented as a list of
tuples [(type,value)] with type = ['char'|'element'].
- If type is 'char' then the value is a character string otherwise
+ If type is 'char' then the value is a character string otherwise
it is a reference to a child node.
"""
self.name = name
self.content = list()
self.attributes = dict()
self.children = defaultdict(list)
-
+
def walk(self, decorators, sub_ws, stack=[]):
result = list()
decorator = decorators.get(self.name, decorators['default'])
result = self.walk(decorators, 1)
if len(result) == 0:
result = None
-
+
return result
def __repr__(self):
result.append('Attr: %s = %s' % (key,value))
for (key,value) in self.children.iteritems():
result.append('Child: %s,%i' % (key,len(value)))
-
+
return '\n'.join(result)
class DoxyContenHandler(object, ContentHandler):
self.counters = defaultdict(int)
self._nodes = None
self._current = None
-
+
def startDocument(self):
pass
-
+
def endDocument(self):
import sys
-
+
def startElement(self, name, attrs):
if name == self.builder.toplevel:
self._nodes = []
-
+
if name == 'memberdef':
kind = attrs.get('kind')
if kind is None:
if self._nodes is None:
return
-
+
node = DocNode(name)
for (key,value) in attrs.items():
node.attributes[key] = value
self._current.children[name].append(node)
self._nodes.append(self._current)
self._current = node
-
+
def characters(self, content):
-
+
if self._current is not None:
self._current.content.append(('char',content.strip()))
-
+
def endElement(self, name):
if name == self.builder.toplevel:
assert(len(self._nodes) == 0)
filepath = '%s/%s' % (xmlpath,filename)
self.parser.parse(open(filepath,'r'))
-
+
class DoxyFuncs(XML2AST):
def __init__(self, path):
super(DoxyFuncs, self).__init__(path,toplevel='memberdef')
else:
print 'not processing node: %s' % node_type
return
-
+
self.objects.append(DocModel(**data))
-
+
def save(self, templates, target_dir):
for obj in self.objects:
template_path = templates[obj.category]
parameters = function_descr['parameters']
for (i,p) in enumerate(node.children['param']):
type_node = p.children['type'][0]
- p_type = self._process_type_node(type_node)
+ p_type = self._process_type_node(type_node)
if p_type[1].find('...') > -1 :
p_name = ''
else:
p_name = None
p_name_node = p.children.get('declname')
if p_name_node is not None:
- p_name = p_name_node[0].getContent()
+ p_name = p_name_node[0].getContent()
(p_direction,p_descr) = param_description_map.get(p_name,(None,None))
-
+
param_descr = {'seqno': i,
'name': p_name,
'direction': p_direction,
parameters.append(param_descr)
result = Function(**function_descr)
print >> self.tmp, result
-
+
return function_descr
def _process_type_node(self, type_node):
"""
- Type node has form
+ Type node has form
<type>type_string</type>
for build in types and
<type>
- <ref refid='reference',kindref='member|compound'>
+ <ref refid='reference',kindref='member|compound'>
'type_name'
</ref></type>
postfix (ex. *, **m, etc.)
p_type = re.sub('KRB5_CALLCONV_WRONG', '', p_type)
p_type = re.sub('KRB5_CALLCONV', '', p_type)
p_type = p_type.strip()
-
+
return (p_type_id, p_type)
def _process_description_node(self, node):
para = node.children.get('para')
result = list()
if para is not None:
- decorators = {'default': self.paragraph_content_decorator}
+ decorators = {'default': self.paragraph_content_decorator}
for e in para:
result.append(str(e.walk(decorators, 1)))
result.append('\n')
return value
else:
return None
-
+
def paragraph_content_decorator(self, node, value):
if node.name == 'para':
return value + '\n'
return None
else:
return value
-
+
def parameter_description_decorator(self, node, value):
if node.name == 'parameterdescription':
return value
return None
else:
return value
-
+
def process_parameter_description(self, node):
"""
Parameter descriptions reside inside detailed description section.
result = dict()
if para is not None:
for e in para:
-
+
param_list = e.children.get('parameterlist')
if param_list is None:
continue
if param_items is None:
continue
for it in param_items:
- decorators = {'default': self.parameter_name_decorator}
+ decorators = {'default': self.parameter_name_decorator}
direction = None
name = it.walk(decorators,0).split(':')
if len(name) == 2:
direction = name[1]
-
+
decorators = {'default': self.parameter_description_decorator,
- 'para': self.paragraph_content_decorator}
- description = it.walk(decorators, 0)
+ 'para': self.paragraph_content_decorator}
+ description = it.walk(decorators, 0)
result[name[0]] = (direction,description)
- return result
+ return result
def _process_return_value_description(self, node):
simplesect_list = p.children.get('simplesect')
if simplesect_list is None:
continue
- for it in simplesect_list:
+ for it in simplesect_list:
decorators = {'default': self.return_value_description_decorator,
- 'para': self.parameter_name_decorator}
+ 'para': self.parameter_name_decorator}
result = it.walk(decorators, 1)
if result is not None:
ret.append(result)
result = " %s %s" % (val, val_descr)
ret.append (result)
return ret
-
+
def return_warning_decorator(self, node, value):
if node.name == 'simplesect':
if node.attributes['kind'] == 'warning':
for (start,end) in zip(breaks[:-1],breaks[1:]):
result.append(value[start:end])
result = '\n'.join(result)
-
+
return result
-
+
def _save(self, table, path = None):
if path is None:
f = sys.stdout
f.write('%s\n' % ','.join(l))
if path is not None:
f.close()
-
-
+
+
class DoxyFuncsTest(DoxyFuncs):
def __init__(self, xmlpath, rstpath):
super(DoxyFuncsTest,self).__init__(xmlpath)
def run_tests(self):
self.test_save()
-
+
def test_run(self):
self.run()
-
+
def test_save(self):
self.run()
templates = {'function': 'func_document.tmpl'}
self.save(templates, self.target_dir)
-
+
if __name__ == '__main__':
tester = DoxyFuncsTest(xmlpath, rstpath)
tester.run_tests()
-
+
'''
Copyright 2011 by the Massachusetts
Institute of Technology. All Rights Reserved.
-
+
Export of this software from the United States of America may
require a specific license from the United States Government.
It is the responsibility of any person or organization contemplating
export to obtain such a license before exporting.
-
+
WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
distribute this software and its documentation for any purpose and
without fee is hereby granted, provided that the above copyright
class DoxyTypes(object):
def __init__(self, xmlpath):
self.xmlpath = xmlpath
-
+
def run_compound(self, filename, include=None):
- path = '%s/%s' % (self.xmlpath,filename)
+ path = '%s/%s' % (self.xmlpath,filename)
tree = etree.parse(path)
root = tree.getroot()
- brief_node = root.xpath('./compounddef/briefdescription')[0]
- brief_description = self._get_brief_description(brief_node)
+ brief_node = root.xpath('./compounddef/briefdescription')[0]
+ brief_description = self._get_brief_description(brief_node)
details_node = root.xpath('./compounddef/detaileddescription')[0]
detailed_description = self._get_detailed_description(details_node)
-
+
fields = list()
for node in root.iterfind(".//memberdef[@kind]"):
data = {}
else:
pass
fields.append(data)
-
+
result = {'brief_description': brief_description,
'detailed_description': detailed_description,
'attributes': fields}
-
+
return result
-
-
-
+
+
+
def run(self, filename, include=None):
"""
- Parses xml file generated by doxygen.
-
+ Parses xml file generated by doxygen.
+
@param filename: doxygen xml file name
- @param include: members sections to include, in None -- include all
+ @param include: members sections to include, in None -- include all
"""
- path = '%s/%s' % (self.xmlpath,filename)
+ path = '%s/%s' % (self.xmlpath,filename)
tree = etree.parse(path)
root = tree.getroot()
result = list()
elif kind == 'define':
data = self._process_define_node(node)
result.append(data)
- print "\nnumber of types processed ==> " , len(result)
+ print "\nnumber of types processed ==> " , len(result)
return result
def _process_typedef_node(self, node):
t_name = node.xpath('./name/text()')[0]
-
+
print t_name
-
+
t_Id = node.attrib['id']
t_definition = node.xpath('./definition/text()')[0]
- t_type = self._process_type_node(node.xpath("./type")[0])
+ t_type = self._process_type_node(node.xpath("./type")[0])
brief_node = node.xpath('./briefdescription')[0]
t_brief = self._get_brief_description(brief_node)
details_node = node.xpath('./detaileddescription')[0]
if not os.path.exists(path):
# nothing can be done
return typedef_descr
-
- compound_info = self.run_compound(filename)
+
+ compound_info = self.run_compound(filename)
if compound_info is not None:
brief_description = compound_info.get('brief_description')
if brief_description is not None and len(brief_description):
# check if this is not a duplicate
if detailed_description.find(t_detailed) < 0:
typedef_descr['long_description'] = '%s\n%s' % \
- (detailed_description,
+ (detailed_description,
typedef_descr['long_description'])
typedef_descr['attributes'] = compound_info['attributes']
return typedef_descr
v_name = node.xpath('./name/text()')[0]
v_Id = node.attrib['id']
v_definition = node.xpath('./definition/text()')[0]
- v_type = self._process_type_node(node.xpath("./type")[0])
+ v_type = self._process_type_node(node.xpath("./type")[0])
brief_node = node.xpath('./briefdescription')[0]
v_brief = self._get_brief_description(brief_node)
details_node = node.xpath('./detaileddescription')[0]
v_definition = re.sub('KRB5_CALLCONV_C', '', v_definition)
v_definition = re.sub('KRB5_CALLCONV', '', v_definition)
v_definition = re.sub('\*', '\\*', v_definition)
-
+
variable_descr = {'category': 'variable',
'definition': v_definition,
'name': v_name,
if len(node.xpath('./initializer')) > 0:
len_ref = len(node.xpath('./initializer/ref'))
if len(node.xpath('./initializer/ref')) > 0:
- d_type = self._process_type_node(node.xpath("./initializer/ref")[0])
+ d_type = self._process_type_node(node.xpath("./initializer/ref")[0])
if len(d_type) > 0:
len_text = len(node.xpath('./initializer/text()'))
if len_text == 0 and d_type[1]:
if len_text > 1:
if node.xpath('./initializer/text()')[1] is not None:
d_initializer = d_initializer + node.xpath('./initializer/text()')[1]
- else:
+ else:
d_initializer = node.xpath('./initializer/text()')[0]
d_Id = node.attrib['id']
brief_node = node.xpath('./briefdescription')[0]
if x is not None and len(x):
result.append(x)
result = '\n'.join(result)
-
+
return result
-
+
def _get_detailed_description(self, node):
"""
a) Content section
b) Return value section -- skip
c) Parameter list section -- skip
- @param node: detailed description node
+ @param node: detailed description node
"""
result = list()
for p in node.xpath("./para"):
return result
def _process_paragraph_content(self, node):
-
+
result = list()
content = node.xpath(".//text()")
for e in content:
def _process_type_node(self, node):
"""
- Type node has form
+ Type node has form
<type>type_string</type>
for build in types and
<type>
- <ref refid='reference',kindref='member|compound'>
+ <ref refid='reference',kindref='member|compound'>
'type_name'
</ref></type>
postfix (ex. *, **m, etc.)
elif len(p_id) == 0:
p_id = None
p_type = ' '.join(node.xpath(".//text()"))
-
+
# remove macros
p_type = re.sub('KRB5_CALLCONV_C', ' ', p_type)
p_type = re.sub('KRB5_CALLCONV', ' ', p_type)
-
+
return (p_id,p_type)
def save(self, obj, templates, target_dir):
template_path = templates[obj.category]
outpath = '%s/%s.rst' % (target_dir,obj.name)
obj.save(outpath, template_path)
-
-
-
+
+
+
class DoxyTypesTest(DoxyTypes):
def __init__(self, xmlpath, rstpath):
self.templates = { 'composite': 'type_document.tmpl'}
self.test_process_typedef_node()
print "Process define's"
self.test_process_define_node()
-
+
def test_run(self):
filename = 'krb5_8hin.xml'
self.run(filename)
-
+
def test_process_variable_node(self):
filename = 'struct__krb5__octet__data.xml'
result = self.run(filename, include=['variable'])
self.save(obj, tmpl, target_dir)
if __name__ == '__main__':
-
+
tester = DoxyTypesTest( xml_inpath, rst_outpath)
tester.run_tests()
:param:
-
+
#for $param in $function.parameters:
#if $param.name is ''
#continue
#set name_description = '**%s**' % $param.name
#end if
#if $param.description is not None
- #set $description= ' - ' + $param.description
+ #set $description= ' - ' + $param.description
#else
- #set $description=''
+ #set $description=''
#end if
$name_description$description
-
+
#end for
..
-#if len($function.retval_description) > 0
+#if len($function.retval_description) > 0
:retval:
-#for $retval in $function.retval_description:
- - $retval
+#for $retval in $function.retval_description:
+ - $retval
#end for
#end if
#if len($function.return_description) > 0
:return:
-#for $retval in $function.return_description:
- - $retval
+#for $retval in $function.return_description:
+ - $retval
#end for
#end if
-
+
..
-
+
#if $function.deprecated_description is not None
$function.deprecated_description
..
#if $function.sa_description is not None
-.. seealso::
+.. seealso::
$function.sa_description
#end if
$composite.definition
-#if $composite.Id is not None
+#if $composite.Id is not None
#if len($composite.attributes)
Members
#end if
-#for $attr in $composite.attributes:
+#for $attr in $composite.attributes:
#if $attr.name is not None
-.. c:member:: $attr.type $composite.name.$attr.name
+.. c:member:: $attr.type $composite.name.$attr.name
$attr.short_description
#if $attr.long_description is not None
- $attr.long_description
+ $attr.long_description
#end if
-
+
#end if
#end for
#end if
projects / thirdparty / krb5.git / commitdiff
