# Module: `sphinxext.custom_doctests`

Handlers for IPythonDirective’s @doctest pseudo-decorator.

The Sphinx extension that provides support for embedded IPython code provides a pseudo-decorator @doctest, which treats the input/output block as a doctest, raising a RuntimeError during doc generation if the actual output (after running the input) does not match the expected output.

An example usage is:

    .. ipython::

         In [1]: x = 1

         @doctest
         In [2]: x + 2
         Out[3]: 3

One can also provide arguments to the decorator. The first argument should be the name of a custom handler. The specification of any other arguments is determined by the handler. For example,

    .. ipython::

       @doctest float
       In [154]: 0.1 + 0.2
       Out[154]: 0.3

allows the actual output `0.30000000000000004` to match the expected output due to a comparison with np.allclose.

This module contains handlers for the @doctest pseudo-decorator. Handlers should have the following function signature:

    handler(sphinx_shell, args, input_lines, found, submitted)

where sphinx_shell is the embedded Sphinx shell, args contains the list of arguments that follow: '@doctest handler_name’, input_lines contains a list of the lines relevant to the current doctest, found is a string containing the output from the IPython shell, and submitted is a string containing the expected output from the IPython shell.

Handlers must be registered in the doctests dict at the end of this module.

## 2 Functions

`IPython.sphinxext.custom_doctests.``str_to_array`(s)

  Simplistic converter of strings from repr to float NumPy arrays.

  If the repr representation has ellipsis in it, then this will fail.

  Parameters:

  s : str

  > The repr version of a NumPy array.

  Examples

      >>> s = "array([ 0.3,  inf,  nan])"
      >>> a = str_to_array(s)

`IPython.sphinxext.custom_doctests.``float_doctest`(sphinx_shell, args, input_lines, found, submitted)

  Doctest which allow the submitted output to vary slightly from the input.

  Here is how it might appear in an rst file:

      .. ipython::

         @doctest float
         In [1]: 0.1 + 0.2
         Out[1]: 0.3