web doc, prettier?

[hainm]

is there any way to make to doc prettier? It's kind of annoying to see this.

5.1.6. Reader/Writer registry
The following data structures connect reader/writer classes to their format identifiers. They are documented for programmers who want to enhance MDAnalysis; the casual user is unlikely to access them directly.

Some formats can either write single frames or trajectories (such as PDB). In theses cases, the kind of writer is selected with the multiframe keyword to MDAnalysis.coordinates.core.get_writer() (or the writer itself).

MDAnalysis.coordinates.__init__._trajectory_readers = {'DMS': <class 'MDAnalysis.coordinates.DMS.DMSReader'>, 'CRD': <class 'MDAnalysis.coordinates.CRD.CRDReader'>, 'DATA': <class 'MDAnalysis.coordinates.LAMMPS.DATAReader'>, 'XPDB': <class 'MDAnalysis.coordinates.PDB.ExtendedPDBReader'>, 'CHAIN': <class 'MDAnalysis.coordinates.base.ChainReader'>, 'DCD': <class 'MDAnalysis.coordinates.DCD.DCDReader'>, 'NC': <class 'MDAnalysis.coordinates.TRJ.NCDFReader'>, 'TRJ': <class 'MDAnalysis.coordinates.TRJ.TRJReader'>, 'MDCRD': <class 'MDAnalysis.coordinates.TRJ.TRJReader'>, 'TRZ': <class 'MDAnalysis.coordinates.TRZ.TRZReader'>, 'XTC': <class 'MDAnalysis.coordinates.xdrfile.XTC.XTCReader'>, 'GMS': <class 'MDAnalysis.coordinates.GMS.GMSReader'>, 'GRO': <class 'MDAnalysis.coordinates.GRO.GROReader'>, 'TRR': <class 'MDAnalysis.coordinates.xdrfile.TRR.TRRReader'>, 'PDB': <class 'MDAnalysis.coordinates.PDB.PDBReader'>, 'HISTORY': <class 'MDAnalysis.coordinates.DLPoly.HistoryReader'>, 'LAMMPS': <class 'MDAnalysis.coordinates.LAMMPS.DCDReader'>, 'Permissive_PDB': <class 'MDAnalysis.coordinates.PDB.PrimitivePDBReader'>, 'INPCRD': <class 'MDAnalysis.coordinates.INPCRD.INPReader'>, 'PDBQT': <class 'MDAnalysis.coordinates.PDBQT.PDBQTReader'>, 'PQR': <class 'MDAnalysis.coordinates.PQR.PQRReader'>, 'XYZ': <class 'MDAnalysis.coordinates.XYZ.XYZReader'>, 'RESTRT': <class 'MDAnalysis.coordinates.INPCRD.INPReader'>, 'CONFIG': <class 'MDAnalysis.coordinates.DLPoly.ConfigReader'>, 'MOL2': <class 'MDAnalysis.coordinates.MOL2.MOL2Reader'>, 'NCDF': <class 'MDAnalysis.coordinates.TRJ.NCDFReader'>}¶
standard trajectory readers (dict with identifier as key and reader class as value)

MDAnalysis.coordinates.__init__._topology_coordinates_readers = {'DMS': <class 'MDAnalysis.coordinates.DMS.DMSReader'>, 'CRD': <class 'MDAnalysis.coordinates.CRD.CRDReader'>, 'GMS': <class 'MDAnalysis.coordinates.GMS.GMSReader'>, 'GRO': <class 'MDAnalysis.coordinates.GRO.GROReader'>, 'DATA': <class 'MDAnalysis.coordinates.LAMMPS.DATAReader'>, 'PDB': <class 'MDAnalysis.coordinates.PDB.PrimitivePDBReader'>, 'HISTORY': <class 'MDAnalysis.coordinates.DLPoly.HistoryReader'>, 'XPDB': <class 'MDAnalysis.coordinates.PDB.ExtendedPDBReader'>, 'MOL2': <class 'MDAnalysis.coordinates.MOL2.MOL2Reader'>, 'PDBQT': <class 'MDAnalysis.coordinates.PDBQT.PDBQTReader'>, 'PQR': <class 'MDAnalysis.coordinates.PQR.PQRReader'>, 'CONFIG': <class 'MDAnalysis.coordinates.DLPoly.ConfigReader'>, 'XYZ': <class 'MDAnalysis.coordinates.XYZ.XYZReader'>}
readers of files that contain both topology/atom data and coordinates (currently only the keys are used)

http://pythonhosted.org/MDAnalysis/documentation_pages/coordinates/init.html#reader-writer-registry

Honestly, no one cares to read if it looks like that.

[orbeckst]

Can you make a suggestion what you'd consider prettier?

These docs are certainly rather meant for developers than users so we could try to make better distinction between user and developer docs. It is also not necessary to show the actual values. Do you know how to tell sphinx autodoc not to show the values?

In general, however, I think more documentation is better than less, and my experience is that it is difficult enough to get developers to write docs so I am inclined to rather err on the side of including documentation than to throw it out. And as always --- PRs are welcome ;-).

[hainm]

Do you know how to tell sphinx autodoc not to show the values? Can you make a suggestion what you'd consider prettier?

I would just exclude it from the website. :D

These docs are certainly rather meant for developers than users so we could try to make better distinction between user and developer docs.

IMO, developers prefer to read the code than reading that autodoc for sure.

my experience is that it is difficult enough to get developers to write docs

In the long term of maintenance, it's better to encourage developers to write more doc.

[richardjgowers]

http://pythonhosted.org/MDAnalysis/documentation_pages/coordinates/init.html#supported-coordinate-formats

I think that dict is the same as this table, so we could probably merge them

[orbeckst]

On 11 Sep, 2015, at 14:44, Richard Gowers wrote:

http://pythonhosted.org/MDAnalysis/documentation_pages/coordinates/init.html#supported-coordinate-formats

I think that dict is the same as this table, so we could probably merge them

The displayed content is not important for the docs of the dicts but the fact that part of the programming API is to add any reader to one of the dicts with these specific names is. This has to be spelled out somewhere explicitly. We could certainly put the whole "Trajectory API" description into its own file.

[dotsdl]

I think it better to create a top-level namespace function, perhaps MDAnalysis.register() that takes in readers and writers and adds them to the appropriate dicts. I recently did this to datreant to make custom Treants identifiable by the collections and other built-in machinery, which is needed for objects such as Sim in MDSynthesis.

If Readers/Writers have attributes with all the information included, then registering a custom-built one would be as simple as:

import MDAnalysis as mda

# add my custom reader
mda.register(MyReader)

# add my custom writer
mda.register(MyWriter)

This would avoid Reader/Writer developers to have to manually deal with the dictionaries; they need only make sure their Reader/Writer has all the necessary components to be processed.

[hainm]

This would avoid Reader/Writer developers to have to manually deal with the dictionaries; they need only make sure their Reader/Writer has all the necessary components to be processed.

+1

[orbeckst]

I like @dotsdl 's suggestion. It does not have to be at the top level, though, MDAnalysis.coordinates is probably sufficient.

Perhaps have the same thing for topology readers as well, with the actual machinery living in lib or core.

Please open a new issue — that was a productive discussion, starting from aesthetics.

[dotsdl]

Done (see #431). I think if we address the problem in this way it would eliminate the need for docs to show registry dictionaries at all. We could simply show usage of the register method and document the required attributes of the Reader/Writer to ensure it registers correctly.

[orbeckst]

WIth #431 raised I am closing this one.