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')