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 installer():
""" build a bash install script """
if os.path.isdir(Project.installer_dir):
info('')
info("=" * 70)
info('building installer')
with cd(Project.installer_dir, verbose=True):
with LocalShell(verbose=True) as local:
if os.path.isfile('installer.conf'):
os.remove('installer.conf')
for f in glob.glob("*.sh"):
os.remove(f)
with open('installer.conf', 'w') as conf:
conf.write(dedent("""\
installer_script="{name}-{version}-installer.sh"
package_name="{name}-{version}.tar.gz"
executable_name="{package}"
snakes="{snakes}"
pip_options="{pip_options}"
""").format(name=Project.name,
version=Project.version,
package=Project.package,
snakes=Project.pythons_str,
pip_options=Project.pip_options))
local.run('/bin/bash build')
def incremental():
"""Incremental build docs for testing purposes"""
with cd(Project.docs_dir):
run_python(
"sphinx-build -b html -d _build/doctrees -w docs.log "
"-n . ../{htmldir}".format(htmldir=Project.docs_html_dir)
)
clean_doc_log("docs.log")
def diagrams():
"""Create UML diagrams"""
if Project.package is not None:
path = os.path.join(Project.herringfile_dir, Project.package)
mkdir_p(Project.uml_dir)
with cd(Project.uml_dir, verbose=True):
_create_module_diagrams(path)
_create_class_diagrams(path)
def publish_gh_pages():
"""copy documentation to github pages"""
if Project.github_url is not None:
tmp_repo_path = None
try:
tmp_repo_path = tempfile.mkdtemp()
with LocalShell(verbose=True) as local:
# clone repo selecting gh-pages branch
# git clone {git_url} {directory}
# git branch --list
local.run("git clone {url} {dir}".format(url=Project.github_url, dir=tmp_repo_path))
with cd(tmp_repo_path, verbose=True):
remote_branches = [
line.lstrip(r"[*\s]*").strip()
for line in local.run("git branch --list -r").splitlines()
]
if "origin/gh-pages" in remote_branches:
local.run("git pull origin")
local.run("git checkout -b gh-pages origin/gh-pages")
# select branch
# git checkout gh-pages
local.run("git checkout gh-pages")
# remove github pages clone directory
# clean_directory(tmp_repo_path)
# touch .nojekyl
touch(".nojekyll")
# copy documentation
if os.path.isdir(Project.docs_html_path):
dir_util.copy_tree(Project.docs_html_path, tmp_repo_path)
# commit and push to github
local.run("git add --all")
local.run("git status")
now = datetime.now().strftime("%c")
message = "{project} Documentation {version} {date}".format(
project=Project.title, version=Project.version, date=now
)
local.run("git commit -m '{message}'".format(message=message))
local.run("git push origin gh-pages")
else:
info("Please create a 'gh-pages' branch on the github repository.")
finally:
if tmp_repo_path is not None:
try:
info("removing {repo}".format(repo=tmp_repo_path))
shutil.rmtree(tmp_repo_path)
except OSError as ex:
if ex.errno != errno.ENOENT:
raise
def watcher():
"""Live view sphinx generated HTML documents"""
with cd(Project.docs_dir):
if not os.path.isdir('_build'):
# very simplistic sanity check. Works for me, as I generally use
# sphinx-quickstart defaults
print('You must run this application from a Sphinx directory containing _build')
else:
do_task()
def pdf_generate():
"""generate PDF using current python environment"""
exclude_from_inheritance_diagrams = getattr(Project, "exclude_from_inheritance_diagrams", None)
_customize_doc_src_files(exclude=exclude_from_inheritance_diagrams)
with cd(Project.docs_dir):
run_python(
"sphinx-build -b pdf -d _build/doctrees -w docs.log "
"-a -E -n . ../{pdfdir}".format(pdfdir=Project.docs_pdf_dir)
)
clean_doc_log("docs.log")
def sphinx():
"""Generate sphinx HTML API documents"""
hack()
if os.path.isdir(Project.docs_html_dir):
shutil.rmtree(Project.docs_html_dir)
with cd(Project.docs_dir):
run_python(
"sphinx-build -b html -d _build/doctrees -w docs.log "
"-v -a -E . ../{htmldir}".format(htmldir=Project.docs_html_dir)
)
clean_doc_log("docs.log")
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 api():
"""Generate API sphinx source files from code"""
if Project.package is not None:
with cd(Project.docs_dir):
exclude = " ".join(Project.exclude_from_docs)
run_python(
"sphinx-apidoc "
"--separate "
"-d 6 "
"-o _src "
"--force "
"../{pkg} {exclude}".format(pkg=Project.package, exclude=exclude)
)
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')
def get_list_of_branch_files():
"""
:return: list of files on the feature branch
"""
with cd(Project.herringfile_dir):
with LocalShell() as local:
if Project.feature_branch is not None:
print("feature branch: " + Project.feature_branch)
command_line = 'git diff --name-only upstream/{branch}'.format(branch=Project.feature_branch)
output = local.system(command_line,
verbose=False)
return [f for f in output.splitlines() if f.startswith('src/')]
return []
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 containers():
"""
Build docker containers.
By default find and build all containers.
If args are present, build just the containers given as command line arguments."""
for root, dirs, files in os.walk(os.path.join(Project.docker_dir, Project.docker_containers_dir)):
# info("root: {root}".format(root=root))
# info("files: {files}".format(files=repr(files)))
if DOCKERFILE in files:
# info("Found Dockerfile in {root}".format(root=root))
repo_dir = split_all(root)[-1]
if not task.argv or repo_dir in task.argv:
tag = "{project}/{dir}".format(project=Project.docker_project, dir=repo_dir)
with cd(root):
with LocalShell() as local:
local.run("docker build -t {tag} .".format(tag=tag).split(' '), verbose=True)
info("built container: {root}".format(root=root))
else:
info("skipping {dir}".format(dir=repo_dir))
def epy():
"""Generate epy API documents"""
with cd(Project.docs_dir):
run_python("epydoc -v --output _epy --graph all bin db dst dut lab otto pc tests util")