idaes.util package

Submodules

idaes.util.sphinxdoctest_plugin module

This module implements pytest plugin for Sphinx doc tests.

In a nutshell, it uses the pytest pytest_collect_file() plugin hook to recognize the Sphinx Makefile. Then it does a quick and dirty parse of that Makefile to extract the command Sphinx is using to run the doctests, which it recognizes by being the first command in the Makefile target named by SPHINX_DOCTEST_TARGET. The parser is able to handle simple Makefile variable expansion, though not currently nested variables so don’t do that.

The mechanics of the pytest plugin mechanism are such that the Makefile is wrapped with a subclass of pytest.File, SphinxMakefile, which implements the collect method to yield a subclass of pytest.Item called SphinxItem, that in turn implements a few methods to run the test and report the result. The bulk of the code in running the test is parsing the output to look for errors, and thus decide whether all the doctests passed, or not.

The drawback of this whole setup is of course some extra complexity. The advantage is that (a) whatever the Makefile does is what this plugin should do, for running the command, as long as the command is the first (and only significant) thing that occurs in the target, and (b) if there ends up being more than one Makefile, it should all continue to work.

exception idaes.util.sphinxdoctest_plugin.SphinxCommandFailed

class idaes.util.sphinxdoctest_plugin.SphinxDoctestFailure(name, parent, details)

class idaes.util.sphinxdoctest_plugin.SphinxDoctestItem(name, parent, wd, cmd)

repr_failure(excinfo)

This is called when self.runtest() raises an exception.

runtest()

Run the Sphinx doctest.

class idaes.util.sphinxdoctest_plugin.SphinxDoctestSuccess(name, parent=None, config=None, session=None, nodeid=None)

exception idaes.util.sphinxdoctest_plugin.SphinxHadErrors

class idaes.util.sphinxdoctest_plugin.SphinxMakefile(fspath, parent=None, config=None, session=None, nodeid=None)

collect()

returns a list of children (items and collectors) for this collection node.

warnings_file

Get warnings and errors output file, if any, from the Sphinx Makefile.

class idaes.util.sphinxdoctest_plugin.SphinxWarnings(fspath, parent=None, config=None, session=None, nodeid=None)

collect()

returns a list of children (items and collectors) for this collection node.

class idaes.util.sphinxdoctest_plugin.SphinxWarningsItem(name, parent, path: pathlib.Path)

repr_failure(excinfo)

This is called when self.runtest() raises an exception.