Doctest Mode

doctest-mode is an Emacs major mode for editing text files that contain Python doctest examples. Doctest is a testing framework for Python that emulates an interactive session, and checks the result of each command. For more information, see the Python library reference documentation on doctest. doctest-mode makes it easier to write and maintain doctest files, by providing:

  • Syntax highlighting of the prompts, source code, and expected output for each doctest example.
  • Editing support, including automatic indentation (similar to python-mode) and automatic prompt management.
  • Execution support, allowing you to run doctest directly from emacs, and examine the results in an output buffer.
  • Failure navigation, allowing you to quickly navigate between failed examples after you run doctest.
  • Output replacement, allowing you to easily update doctest examples with the correct output value.


Using doctest-mode

Walk-through A brief demo of doctest-mode's features.
Commands A summary of the commands provided by doctest-mode.
Customization How to customize the appearance & behavior of doctest-mode.
Doctest submodes How to use doctest-mode inside other modes (0.5alpha only).

Installing doctest-mode

  1. Download and save doctest-mode.el.

  2. Copy doctest-mode.el to a directory that's on your Emacs load-path. (To see your Emacs load-path, type "control-h v load-path" in Emacs.) Alternatively, you can add the following line to your Emacs configuration file:

    (add-to-list 'load-path "...path to dir containing doctest-mode.el...")
  3. Add the following lines to your Emacs configuration file:

    (add-to-list 'auto-mode-alist '("\\.doctest$" . doctest-mode))
    (autoload 'doctest-mode "doctest-mode" "doctest mode" t)
  4. Restart Emacs (or reload your configuration file).

Report a Bug

  • Please email me to report any bugs in doctest-mode, or any incompatibilities with specific versions of Emacs.