def all_doc(tenv, module_names=None, script_paths=None, module_output_dir="",
script_output_dir="", module_overwrite=False,
script_overwrite=False, source_dir=""):
"""Generates documentation for modules and scripts.
:param tenv: Templating environment, retrieved e.g. by
:func:`sphinkydocext.templating.templating_environment`.
:param module_names: Root module names, documentation is generated
recursively for all the submodules.
:param script_paths: List of paths to scripts, creates documentation files
for these.
:param module_output_dir: Output directory of generated module documents.
**Must be relative path to source root.**
:param script_output_dir: Output directory of generated script documents.
**Must be relative path to source root.**
:param source_dir: Source directory, preferably absolute path.
:returns: Tuple of generated module paths, and generated script paths.
"""
module_names = module_names or []
script_paths = script_paths or []
module_files = []
script_files = []
for m in module_names:
try:
module_files.extend(recursive_module_doc(tenv, m,
output_dir=module_output_dir,
source_dir=source_dir,
overwrite=module_overwrite))
except GenerateDocError, er:
log.warning("Unable to generating module doc for '%s': %s",
m, unicode(er))
def recursive_module_doc(tenv, module_name, output_dir="", source_dir="",
overwrite=False):
"""Recursively generates module documentation also for all submodules,
and subpackages.
:param tenv: Jinja2 templating environment. :param module_name: Module
:param source_dir: Source directory.
:param output_dir: Output directory of generated documents. **Must be
relative to the source directory!** :returns: List of generated document
paths.
"""
module_files = []
# We must try to import the module, so we can recurse to the submodules
try:
module, _name = import_by_name(module_name)
except ImportError:
log.warning("Unable to import '%s', docs for this module cannot "
"be generated.", module_name)
else:
# Try to generate documentation for this module
try:
module_files.append(\
module_doc(tenv, module_name, output_dir=output_dir,
source_dir=source_dir, overwrite=overwrite))
except GenerateDocError, er:
log.warning("Unable to generate module doc for '%s': %s",
module_name, unicode(er))
# Continue to found submodules
for submodule_name in get_submodules(module):
module_files.extend(\
recursive_module_doc(tenv, _name + "." + submodule_name,
output_dir=output_dir,
source_dir=source_dir,
overwrite=overwrite))
try:
module_files.extend(recursive_module_doc(tenv, m,
output_dir=module_output_dir,
source_dir=source_dir,
overwrite=module_overwrite))
except GenerateDocError, er:
log.warning("Unable to generating module doc for '%s': %s",
m, unicode(er))
for s in script_paths:
try:
script_files.append(script_doc(tenv, s, output_dir=script_output_dir,
source_dir=source_dir,
overwrite=script_overwrite))
except GenerateDocError, er:
log.warning("Unable to generating script doc for '%s': %s",
s, unicode(er))
return module_files, script_files
def recursive_module_doc(tenv, module_name, output_dir="", source_dir="",
overwrite=False):
"""Recursively generates module documentation also for all submodules,
and subpackages.
:param tenv: Jinja2 templating environment. :param module_name: Module
:param source_dir: Source directory.
:param output_dir: Output directory of generated documents. **Must be
relative to the source directory!** :returns: List of generated document
paths.