SimTk/mdtraj — pull request #570 by mpharrigan (2014-09-04 18:06:27+00:00)
Title: Fixdocs2

Some of the sphinx extensions included are not compatible with python 3. Where possible, I changed `conf.py` to use the actively maintained extensions from their respective packages. I tidied up the custom(?) extensions. I added a note to "Building the docs" about the pitfalls of py3.

Everything seems to work, although the build gives 14,000 warnings
```
[snip]
None:None: WARNING: toctree contains reference to nonexisting document 'api/generated/mdtraj.reporters.NetCDFReporter.report'
None:None: WARNING: toctree contains reference to nonexisting document 'api/generated/mdtraj.reporters.DCDReporter.backend'
None:None: WARNING: toctree contains reference to nonexisting document 'api/generated/mdtraj.reporters.DCDReporter.close'
None:None: WARNING: toctree contains reference to nonexisting document 'api/generated/mdtraj.reporters.DCDReporter.describeNextReport'
None:None: WARNING: toctree contains reference to nonexisting document 'api/generated/mdtraj.reporters.DCDReporter.report'

copying static files... done
copying extra files... done
dumping search index... done
dumping object inventory... done
build succeeded, 14239 warnings.
```

Relevant stack overflow is
http://stackoverflow.com/questions/12206334/sphinx-autosummary-toctree-contains-reference-to-nonexisting-document-warnings

Making that change results in a reduction but not elimination of warnings:
```
[snip]
None:None: WARNING: toctree contains reference to nonexisting document 'api/generated/mdtraj.formats.HDF5TrajectoryFile.constraints'
None:None: WARNING: toctree contains reference to nonexisting document 'api/generated/mdtraj.formats.PDBTrajectoryFile.positions'
None:None: WARNING: toctree contains reference to nonexisting document 'api/generated/mdtraj.formats.PDBTrajectoryFile.topology'
None:None: WARNING: toctree contains reference to nonexisting document 'api/generated/mdtraj.formats.PDBTrajectoryFile.closed'

copying static files... done
copying extra files... done
dumping search index... done
dumping object inventory... done
build succeeded, 2791 warnings.
```