Exhale Deploy Module

The deploy module is responsible for two primary actions:

  1. Executing Doxygen (if requested in exhale_args).

  2. Launching the full API generation via the explode() function.

Doxygen Execution Functions

exhale.deploy._generate_doxygen(doxygen_input)[source]

This method executes doxygen based off of the specified input. By the time this method is executed, it is assumed that Doxygen is intended to be run in the current working directory. Search for returnPath in the implementation of apply_sphinx_configurations() for handling of this aspect.

This method is intended to be called by generateDoxygenXML(), which is in turn called by apply_sphinx_configurations().

Two versions of the doxygen command can be executed:

  1. If doxygen_input is exactly "Doxyfile", then it is assumed that a Doxyfile exists in the current working directory. Meaning the command being executed is simply doxygen.

  2. For all other values, doxygen_input represents the arguments as to be specified on stdin to the process.

Parameters
doxygen_input (str)

Either the string "Doxyfile" to run vanilla doxygen, or the selection of doxygen inputs (that would ordinarily be in a Doxyfile) that will be communicate``d to the ``doxygen process on stdin.

Note

If using Python 3, the input must still be a str. This method will convert the input to bytes as follows:

if sys.version[0] == "3":
    doxygen_input = bytes(doxygen_input, "utf-8")
Return
str or None

If an error occurs, a string describing the error is returned with the intention of the caller raising the exception. If None is returned, then the process executed without error. Example usage:

status = _generate_doxygen("Doxygen")
if status:
    raise RuntimeError(status)

Though a little awkward, this is done to enable the intended caller of this method to restore some state before exiting the program (namely, the working directory before propagating an exception to sphinx-build).

exhale.deploy._valid_config(config, required)[source]

Todo

add documentation of this method

config: doxygen input we’re looking for required: if True, must be present. if False, NOT ALLOWED to be present

exhale.deploy.generateDoxygenXML()[source]

Library API Generation

exhale.deploy.explode()[source]

This method assumes that apply_sphinx_configurations() has already been applied. It performs minimal sanity checking, and then performs in order

  1. Creates a ExhaleRoot object.

  2. Executes parse() for this object.

  3. Executes generateFullAPI() for this object.

  4. Executes toConsole() for this object (which will only produce output when verboseBuild is True).

This results in the full API being generated, and control is subsequently passed back to Sphinx to now read in the source documents (many of which were just generated in containmentFolder), and proceed to writing the final output.