def run_sphinx():
"""
Run sphinx
"""
global doc_errors
if os.path.isdir(Project.docs_html_dir):
shutil.rmtree(Project.docs_html_dir)
options = [
'-a', # always write all output files
'-E', # don't use saved environment
# '-j 4', # distribute the build of N processes WARNING: breaks jenkins
# '-n', # run in nit-picky mode
# '-v', # increase verbosity
# '-q', # do not output anything on standard output, warnings and errors go to stderr
# '-Q', # do not output anything on standard output. Suppress warnings. Only errors go to stderr
]
with cd(Project.docs_dir):
with open("sphinx-build.log", "w") as outputter:
if os.path.isfile('_build/doctrees/index.doctree'):
output = run_python('sphinx-build -v -b html -d _build/doctrees -w docs.log {options} . '
'../{htmldir}'.format(options=' '.join(options),
htmldir=Project.docs_html_dir),
doc_errors=doc_errors)
else:
output = run_python('sphinx-build -v -b html -w docs.log {options} . '
'../{htmldir}'.format(options=' '.join(options), htmldir=Project.docs_html_dir),
doc_errors=doc_errors)
outputter.write(output)
clean_doc_log('docs.log')
def _create_class_diagrams(path):
"""
Create class UML diagram
:param path: path to the module file.
:type path: str
"""
info("_create_class_diagrams")
if not executables_available(['pynsource']):
warning('pynsource not available')
return
files = [os.path.join(dir_path, f)
for dir_path, dir_names, files in os.walk(path)
for f in fnmatch.filter(files, '*.py')]
debug("files: {files}".format(files=repr(files)))
with open(os.path.join(Project.docs_dir, "pynsource.log"), "w") as outputter:
for src_file in files:
debug(src_file)
name = src_file.replace(Project.herringfile_dir + '/', '').replace('.py', '.png').replace('/', '.')
output = "classes_{name}".format(name=name)
debug(output)
if not os.path.isfile(output) or (os.path.isfile(output) and is_newer(output, src_file)):
output = run_python("pynsource -y {output} {source}".format(output=output, source=src_file),
verbose=False, ignore_errors=True)
outputter.write(output)
def _create_module_diagrams(path):
"""
create module UML diagrams
:param path: the module path
:type path: str
"""
info("_create_module_diagrams")
if not executables_available(['pyreverse']):
warning('pyreverse not available')
return
with open(os.path.join(Project.docs_dir, "pyreverse.log"), "w") as outputter:
for module_path in [root for root, dirs, files in os.walk(path) if os.path.basename(root) != '__pycache__']:
debug("module_path: {path}".format(path=module_path))
init_filename = os.path.join(module_path, '__init__.py')
if os.path.exists(init_filename):
info(init_filename)
name = os.path.basename(module_path).split(".")[0]
output = run_python('pyreverse -o svg -p {name} {module} '.format(name=name, module=module_path),
verbose=True, ignore_errors=True)
outputter.write(output)
errors = [line for line in output.splitlines() if not line.startswith('parsing')]
if errors:
info(errors)
def api():
"""Generate API sphinx source files from code"""
global doc_errors
Project.docs_feature_dirs = docs_feature_dirs()
Project.docs_feature_files = get_list_of_branch_files()
if Project.package is not None:
with cd(Project.docs_dir):
exclude = ' '.join(Project.exclude_from_docs)
if Project.package_subdirs:
dirs = [d for d in os.listdir("../{pkg}".format(pkg=Project.package)) if '.' not in d]
for subdir in dirs:
with open("apidoc-{dir}.log".format(dir=subdir), "w") as outputter:
output = run_python("sphinx-apidoc "
"--separate "
"-d 6 "
"-o _src "
"--force "
"../{pkg}/{dir} {exclude}".format(pkg=Project.package,
dir=subdir,
exclude=exclude),
doc_errors=doc_errors)
outputter.write(output)
with open("_src/modules.rst", "w") as modules_file:
modules_file.write(dedent("""\
Modules
=======
.. toctree::
:maxdepth: 6
{mods}
""").format(mods="\n ".join(dirs)))
else:
with open("apidoc.log", "w") as outputter:
output = run_python("sphinx-apidoc "
"--separate "
"-d 6 "
"-o _src "
"--force "
"../{pkg} {exclude}".format(pkg=Project.package,
exclude=exclude),
doc_errors=doc_errors)
outputter.write(output)
def incremental():
"""Incremental build docs for testing purposes"""
with cd(Project.docs_dir):
with open("incremental.log", "w") as outputter:
# noinspection PyArgumentEqualDefault
output = run_python('sphinx-build -b html -d _build/doctrees -w docs.log '
'-n . ../{htmldir}'.format(htmldir=Project.docs_html_dir),
verbose=True,
doc_errors=doc_errors)
outputter.write(output)
clean_doc_log('docs.log')
def hieroglyph_slides():
"""Create presentation slides using Hieroglyph (http://docs.hieroglyph.io/en/latest/index.html)"""
global doc_errors
if os.path.isdir(Project.docs_slide_dir):
shutil.rmtree(Project.docs_slide_dir)
with cd(Project.docs_dir):
with open("slides.log", "w") as outputter:
output = run_python('sphinx-build -b slides -d _build/doctrees -w docs.log '
'-a -E . ../{slide_dir}'.format(slide_dir=Project.docs_slide_dir),
doc_errors=doc_errors)
outputter.write(output)
clean_doc_log('docs.log')
def pdf_generate():
"""generate PDF using current python environment"""
global doc_errors
if Project.enhanced_docs:
diagrams()
hack()
with cd(Project.docs_dir):
with open("pdf.log", "w") as outputter:
output = run_python('sphinx-build -b pdf -d _build/doctrees -w docs.log '
'-a -E -n . ../{pdfdir}'.format(pdfdir=Project.docs_pdf_dir),
doc_errors=doc_errors)
outputter.write(output)
clean_doc_log('docs.log')
