Make — Automated Documentation Builder

While still being actively worked on, the ideal usage would begin with the user in the ../docs directory of the repository and running.:

python3 sphinx_extensions/make html

Where html can be replaced with one of html, singlehtml, doctest or linkcheck. Not all sphinx-build options are currently supported.

Moving output files

>>> import shutil
>>> from os.path import join as pjoin
>>> import subprocess
>>> BUILD_DIR = pjoin('build', 'html')
>>> if shutil.which('rsync'):
>>>     subprocess.run(['rsync', '-hv8r', BUILD_DIR, '.'])

You could even add one of the delete on destination options that rsync has.

One of them specifies to delete anything at the destination not in source. Obviously be careful beforehand but that could be a really simple way to automatically keep the documentation fresh.

See Also

See also

sphinx.cmd.build

The main entrypoint for sphinx and a good module to get comfortable with.

sphinx.cmd.make_main

The pure python replacement for a Makefile.

sphinx.util.osutil

OS utilities.

API

class DocBuilder(build_type, num_jobs, verbosity)

Class to wrap the different commands of this script.

All public methods of this class can be called as parameters of the script.

Attr kind

str The filetype make invokes sphinx-build to create.

Parameters

• kind – str, optional The kind of document sphinx-build will create. Defaults to html.

• num_jobs – int, optional Number of jobs to run the build in parallel with.

• verbosity – bool, optional Run verbosely

DocBuilder Examples

>>> from default_profile.sphinxext.make import DocBuilder
>>> d = DocBuilder('html')
>>> print(d.kind)
'html'

Autogenerated Sphinx Docs

parse(app: sphinx.application.Sphinx, text: str, docname: str = 'index') → docutils.nodes.document

Parse a string as reStructuredText with Sphinx application.

class DocBuilder(kind=None, num_jobs=1, verbosity=0, root: Optional[os.PathLike] = None)

Bases: object

__init__(kind=None, num_jobs=1, verbosity=0, root: Optional[os.PathLike] = None)

static status(output)

Print output in bold. Emits ANSI escape sequences to sys.stdout

cleanup()

Clean the working tree.

sphinx_build(kind, BUILD_PATH: Optional[os.PathLike] = None)

Build docs.

Examples

>>> DocBuilder(num_jobs=4).sphinx_build('html')

run(kind)

Run sphinx-build.

The check argument to subprocess.run() is not enabled so there’s no need to catch subprocess.CalledProcessError().

open_browser(doc: Optional[os.PathLike] = None)

Open a browser tab to the provided document.

Parameters

doc – path to index.html

Type

str

class Runner(*args, **kwargs)

Bases: object

Initializes a DocBuilder and proxies sphinx-build subcommands.

__init__(*args, **kwargs)

Initialized with the same args as DocBuilder.

html()

man()

doctest()

texinfo()

singlehtml()

text()

linkcheck()

generate_autosummary(**kwargs)

class UserSphinxAdditions(sphinx: sphinx.application.Sphinx)

Bases: object

__init__(sphinx: sphinx.application.Sphinx)

classmethod additions(method, **kwargs)

generate_sphinx_app(root: os.PathLike, namespace: Optional[argparse.Namespace] = None)

Generate the primary Sphinx application object that drives the project.

Parameters

• root (str or pathlib.Path) – The root of the repositories docs

• namespace (arparse.NameSpace) – User provided arments.

Returns

app – sphinx.application.Sphinx instance.

Return type

Sphinx

get_jinja_loader(template_path: Union[str, os.PathLike]) → jinja2.loaders.FileSystemLoader

setup_jinja(path_to_template: Union[str, os.PathLike]) → jinja2.environment.Environment

Use jinja to set up the Sphinx environment.

class Maker(source_dir: os.PathLike, build_dir: os.PathLike, builder: List, *args: List, **kwargs: Dict)

Bases: sphinx.cmd.make_mode.Make

__init__(source_dir: os.PathLike, build_dir: os.PathLike, builder: List, *args: List, **kwargs: Dict)

run(builder: Union[List, None, AnyStr] = None, *args, **kwargs)

Run sphinx-build with as many options given reasonable defaults as possible.

create_sphinx_config(confdir: os.PathLike)

Create a sphinx.config.Config object which isn’t utilized currently.

Simply here as a thorough method to check for syntax errors.

main(repo_root: os.PathLike, argv=None)

Create the required objects to simulate the sphinx make-main command.

Create a jinja2.Environment, a sphinx.project.Project, sphinx.jinja2glue.SphinxFileSystemLoader.

get_git_root() → pathlib.Path