### Navigation

- index
- modules |
- next |
- previous |
- home|
- search|
- documentation »
- The IPython API »

# testing.mkdoctests

## Module: `testing.mkdoctests`

Inheritance diagram for `IPython.testing.mkdoctests`:

Utility for making a doctest file out of Python or IPython input.

> %prog [options] input_file [output_file]

This script is a convenient generator of doctest files that uses IPython’s irunner script to execute valid Python or IPython input in a separate process, capture all of the output, and write it to an output file.

It can be used in one of two ways:

1. With a plain Python or IPython input file (denoted by extensions ‘.py’ or ‘.ipy’. In this case, the output is an auto-generated reST file with a basic header, and the captured Python input and output contained in an indented code block.

   If no output filename is given, the input name is used, with the extension replaced by ‘.txt’.

2. With an input template file. Template files are simply plain text files with special directives of the form

   %run filename

   to include the named file at that point.

   If no output filename is given and the input filename is of the form ‘base.tpl.txt’, the output will be automatically named ‘base.txt’.

## Classes

### `IndentOut`

class `IPython.testing.mkdoctests.``IndentOut`(out=<open file '<stdout>', mode 'w' at 0x2b38de9eb1e0>, indent=4)

  Bases: `object`

  A simple output stream that indents all output by a fixed amount.

  Instances of this class trap output to a given stream and first reformat it to indent every input line.

  `__init__`(out=<open file '<stdout>', mode 'w' at 0x2b38de9eb1e0>, indent=4)

    Create an indented writer.

    Keywords : |

    - out : stream (sys.stdout) Output stream to actually write to after indenting.
    - indent : int Number of spaces to indent every input line by.
  `close`()
  `flush`()
  `write`(data)

    Write a string to the output stream.

### `RunnerFactory`

class `IPython.testing.mkdoctests.``RunnerFactory`(out=<open file '<stdout>', mode 'w' at 0x2b38de9eb1e0>)

  Bases: `object`

  Code runner factory.

  This class provides an IPython code runner, but enforces that only one runner is every instantiated. The runner is created based on the extension of the first file to run, and it raises an exception if a runner is later requested for a different extension type.

  This ensures that we don’t generate example files for doctest with a mix of python and ipython syntax.

  `__init__`(out=<open file '<stdout>', mode 'w' at 0x2b38de9eb1e0>)

    Instantiate a code runner.

## Function

`IPython.testing.mkdoctests.``main`()

  Run as a script.

### Navigation

- index
- modules |
- next |
- previous |
- home|
- search|
- documentation »
- The IPython API »