I was proposing to adopt doctest in the biopython project (modules for
bioinformatics in python, http://biopython.org/).

Doctest is very useful to document modules that will be used by many
other people: for example, there are many different file formats in
bioinformatics, and it is very useful to add an example of the file to
be parsed in the documentation of a file parser.
Look at my code here: 
-
http://github.com/dalloliogm/biopython---popgen/blob/980419dbc0666e2578c2486dab1fef23ccfbb72c/src/PopGen/Gio/TpedIO.py


However, it is very uncomfortable to have to create a file-like object
in every docstring, especially when you want to document the methods of
a class.
It would be useful if at least the doctests of the methods of a class
share the objects created in the main doctest of the class.

Let's say I have a class called FastaIO (fasta is a file format for
sequence).
This module would have many methods: format, to_dict (returns a
dictionary of the sequences included in the file), and many others.
The main docstring of the class will have an example of a fasta file,
and shows how to create an instance of FastaIO.
It is silly to have to repeat this example (creating an instance of
FastaIO) in every submethod. Moreover, it is more difficult to maintain
and more error prone (imagine you have a class with one hundred methods).