Use doctest for examples in doc-strings

[kain88-de]

The examples we have in doc-strings are currently not always up to date. I would guess that a fair number of them actually doesn't work with the current code. My suggestion to fix this is to integrate doctest into our standard testing on travis and our local workstations.

I haven't tried doctest yet for myself and I assume in the beginning we have to make it optional in travis because a lot of them are failing.

Note: Since getting all examples in the doc-strings to pass is a large amount of work this is a good project for GSoC students who aren't very familiar with python or molecular simulations.

[kain88-de]

You can assign yourself to the issue so that nobody else starts working on it.

[kdexd]

As far as I know, the rights of assigning an issue to someone works only among the owners of the repository..

Though I am acknowledging the readers here that I am trying this out currently - to avoid work duplication.

[jbarnoud]

@karandesai-96 @kain88-de Not only that, but we can only assign "collaborator" and member of the organisation. Here is what the documentation says:

You can only create assignments for yourself, collaborators on personal projects, or members of your organization with read permissions on the repository.

[kain88-de]

@jbarnoud good to know. I always assumed we could assign any one.

[kdexd]

Github had been throwing Remote hung up unexpectedly errors today. I am finally able to clone the repo, will start my work upon it. I had a quick question:

• Which testing framework is used by MDAnalysis currently ?
• If it is documented somewhere, where do I look upon ? 😄

[jbarnoud]

We use nosetests with a bunch of ad-hoc plug-ins. See the wiki for more details. On a more general note, have a look at the developer guide we have on the wiki.

[tylerjereddy]

Yeah, this is probably a step in the right direction, though I would predict quite a lot of work before all example doctests would work perfectly. When I have used doctest in my own projects I've found it to be very sensitivie--you really have to use some tricks here and there to suppress output that can change over time like the memory ID things that get produced with matplotlib plots and so on.

[orbeckst]

Do we want to continue looking at doc test for MDAnalysis?

I am not in favor; it seems to require a lot of work to make it work and to integrate it into the existing tests.

I would also not put too much effort into it while we are trying to

• change the test infrastructure Migrate from nose to py.test #884
• restructure the docs Restructure documentation for user-friendliness #1175

[kain88-de]

This is not something to do right now but I would really like to have a closer look into this after the migration to pytest and python3. The simple reason is that I often find outdated docs in the source code. The worst example sometimes don't even work anymore. doctests are the only way I know of to ensure that our example-code in the docs continues to work.

[lilyminium]

I wouldn't mind getting this done for 2.0, but to put doctest in the CI suite we'll need it to actually pass first. I'll treat this as the overall issue and raise separate ones for changes per module.

Some kind of example_universe would be helpful to avoid repeating the creation of universes though.

>>> pytest . --disable-pytest-warnings --doctest-modules

=========================================== short test summary info ===========================================
FAILED __init__.py::MDAnalysis
FAILED analysis/align.py::MDAnalysis.analysis.align
FAILED analysis/align.py::MDAnalysis.analysis.align.rotation_matrix
FAILED analysis/psa.py::MDAnalysis.analysis.psa.discrete_frechet
FAILED analysis/psa.py::MDAnalysis.analysis.psa.hausdorff
FAILED analysis/psa.py::MDAnalysis.analysis.psa.hausdorff_avg
FAILED analysis/psa.py::MDAnalysis.analysis.psa.hausdorff_wavg
FAILED analysis/rms.py::MDAnalysis.analysis.rms.rmsd
FAILED analysis/encore/similarity.py::MDAnalysis.analysis.encore.similarity
FAILED analysis/encore/similarity.py::MDAnalysis.analysis.encore.similarity.ces
FAILED analysis/encore/similarity.py::MDAnalysis.analysis.encore.similarity.ces_convergence
FAILED analysis/encore/similarity.py::MDAnalysis.analysis.encore.similarity.dres
FAILED analysis/encore/similarity.py::MDAnalysis.analysis.encore.similarity.dres_convergence
FAILED analysis/encore/similarity.py::MDAnalysis.analysis.encore.similarity.hes
FAILED analysis/encore/clustering/cluster.py::MDAnalysis.analysis.encore.clustering.cluster.cluster
FAILED analysis/encore/dimensionality_reduction/reduce_dimensionality.py::MDAnalysis.analysis.encore.dimensionality_reduction.reduce_dimensionality.reduce_dimensionality
FAILED converters/OpenMM.py::MDAnalysis.converters.OpenMM
FAILED converters/ParmEd.py::MDAnalysis.converters.ParmEd
FAILED converters/ParmEdParser.py::MDAnalysis.converters.ParmEdParser
FAILED converters/RDKit.py::MDAnalysis.converters.RDKit
FAILED converters/RDKit.py::MDAnalysis.converters.RDKit.RDKitConverter
FAILED coordinates/GRO.py::MDAnalysis.coordinates.GRO
FAILED coordinates/LAMMPS.py::MDAnalysis.coordinates.LAMMPS
FAILED coordinates/TRJ.py::MDAnalysis.coordinates.TRJ.NCDFWriter
FAILED coordinates/base.py::MDAnalysis.coordinates.base.Timestep.triclinic_dimensions
FAILED coordinates/chain.py::MDAnalysis.coordinates.chain.filter_times
FAILED coordinates/chemfiles.py::MDAnalysis.coordinates.chemfiles
FAILED core/accessors.py::MDAnalysis.core.accessors.Accessor
FAILED core/groups.py::MDAnalysis.core.groups.AtomGroup
FAILED core/groups.py::MDAnalysis.core.groups.AtomGroup.select_atoms
FAILED core/groups.py::MDAnalysis.core.groups.AtomGroup.sort
FAILED core/groups.py::MDAnalysis.core.groups.AtomGroup.unique
FAILED core/groups.py::MDAnalysis.core.groups.AtomGroup.write
FAILED core/groups.py::MDAnalysis.core.groups.GroupBase.accumulate
FAILED core/groups.py::MDAnalysis.core.groups.GroupBase.center
FAILED core/groups.py::MDAnalysis.core.groups.GroupBase.concatenate
FAILED core/groups.py::MDAnalysis.core.groups.GroupBase.groupby
FAILED core/groups.py::MDAnalysis.core.groups.GroupBase.intersection
FAILED core/groups.py::MDAnalysis.core.groups.GroupBase.isunique
FAILED core/groups.py::MDAnalysis.core.groups.GroupBase.subtract
FAILED core/groups.py::MDAnalysis.core.groups.GroupBase.symmetric_difference
FAILED core/groups.py::MDAnalysis.core.groups.GroupBase.union
FAILED core/groups.py::MDAnalysis.core.groups.ResidueGroup.unique
FAILED core/groups.py::MDAnalysis.core.groups.SegmentGroup.unique
FAILED core/selection.py::MDAnalysis.core.selection.grab_not_keywords
FAILED core/selection.py::MDAnalysis.core.selection.join_separated_values
FAILED core/topology.py::MDAnalysis.core.topology.make_downshift_arrays
FAILED core/topologyobjects.py::MDAnalysis.core.topologyobjects.Bond
FAILED core/topologyobjects.py::MDAnalysis.core.topologyobjects.TopologyDict
FAILED core/universe.py::MDAnalysis.core.universe.Universe.add_Residue
FAILED core/universe.py::MDAnalysis.core.universe.Universe.add_TopologyAttr
FAILED core/universe.py::MDAnalysis.core.universe.Universe.del_TopologyAttr
FAILED core/universe.py::MDAnalysis.core.universe.Universe.empty
FAILED core/universe.py::MDAnalysis.core.universe.Universe.from_smiles
FAILED lib/picklable_file_io.py::MDAnalysis.lib.picklable_file_io.BZ2Picklable
FAILED lib/picklable_file_io.py::MDAnalysis.lib.picklable_file_io.FileIOPicklable
FAILED lib/picklable_file_io.py::MDAnalysis.lib.picklable_file_io.GzipPicklable
FAILED lib/transformations.py::MDAnalysis.lib.transformations
FAILED lib/transformations.py::MDAnalysis.lib.transformations._py_clip_matrix
FAILED lib/transformations.py::MDAnalysis.lib.transformations._py_quaternion_slerp
FAILED lib/transformations.py::MDAnalysis.lib.transformations._py_rotation_matrix
FAILED lib/transformations.py::MDAnalysis.lib.transformations._py_scale_matrix
FAILED lib/transformations.py::MDAnalysis.lib.transformations._py_shear_matrix
FAILED lib/transformations.py::MDAnalysis.lib.transformations._py_superimposition_matrix
FAILED lib/transformations.py::MDAnalysis.lib.transformations.rotation_from_matrix
FAILED lib/transformations.py::MDAnalysis.lib.transformations.scale_from_matrix
FAILED lib/transformations.py::MDAnalysis.lib.transformations.shear_from_matrix
FAILED lib/util.py::MDAnalysis.lib.util.check_coords
FAILED lib/util.py::MDAnalysis.lib.util.unique_rows
FAILED topology/LAMMPSParser.py::MDAnalysis.topology.LAMMPSParser
================================= 70 failed, 41 passed, 9 warnings in 21.12s ==================================

[hmacdope]

Perhaps we can reconsider this for 3.0 @MDAnalysis/coredevs? I think automated doc testing would be a big improvement. I will add to the 3.0 milestone and we can pull out following discussion?

[hmacdope]

Linked to #3925