Updated the CHEMFILES docs (MDAnalysis#3128)

## Work done in this PR
- Fixes broken link to the chemfiles format
- Adds chemfiles to list of supported file formats
- Adds examples for reading and writing files using chemfiles

package/MDAnalysis/coordinates/__init__.py

@@ -260,6 +260,10 @@ class can choose an appropriate reader automatically.
    | H5MD          | h5md      |  r    | H5MD_ file format for coordinates                    |
    |               |           |       | :mod:`MDAnalysis.coordinates.H5MD`                   |
    +---------------+-----------+-------+------------------------------------------------------+
+   | `chemfiles`_  | CHEMFILES |  r/w  | interface to `chemfiles`_, see the `list of chemfiles|
+   | library       |           |       | file formats`_ and                                   |
+   |               |           |       | :mod:`MDAnalysis.coordinates.chemfiles`              |
+   +---------------+-----------+-------+------------------------------------------------------+   
 
 .. [#a] This format can also be used to provide basic *topology*
    information (i.e. the list of atoms); it is possible to create a
@@ -268,6 +272,8 @@ class can choose an appropriate reader automatically.
 
 .. _`netcdf4-python`: https://github.com/Unidata/netcdf4-python
 .. _`H5MD`: https://nongnu.org/h5md/index.html
+.. _`chemfiles`: https://chemfiles.org/
+.. _`list of chemfiles file formats`: https://chemfiles.org/chemfiles/latest/formats.html
 
 .. _Trajectory API:
 

package/MDAnalysis/coordinates/chemfiles.py

@@ -20,24 +20,64 @@
 # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
 #
 """
-Reading trajectory with Chemfiles --- :mod:`MDAnalysis.coordinates.chemfiles`
-=============================================================================
+Reading trajectories with *chemfiles* --- :mod:`MDAnalysis.coordinates.chemfiles`
+=================================================================================
 
-Classes to read and write files using the `chemfiles`_ library. This library
-provides C++ implementation of multiple formats readers and writers, the full
-list if available `here <formats>`_.
+MDAnalysis interoperates with the `chemfiles`_ library. The *chemfiles* C++ library 
+supports an expanding set of file formats, some of which are not natively supported by
+MDAnalysis. Using the *CHEMFILES* reader you can use  `chemfiles`_ for the low-level 
+file reading. Check the list of `chemfile-supported file formats <formats>`_.
 
 .. _chemfiles: https://chemfiles.org
-.. _formats: http://chemfiles.org/chemfiles/latest/formats.html
+.. _formats: https://chemfiles.org/chemfiles/0.9.3/formats.html#list-of-supported-formats
+.. NOTE: MDAnalysis currently restricts chemfiles to 0.9 <= version < 0.10. Update the link
+..       above to the latest documentation once this restriction is lifted.
+..       https://chemfiles.org/chemfiles/latest/formats.html#list-of-supported-formats
+
+Using the CHEMFILES reader
+--------------------------
+
+When reading, set the ``format="CHEMFILES"`` keyword argument and I/O is delegated to 
+`chemfiles`_. For example::
+
+   >>> import MDAnalysis as mda
+   >>> from MDAnalysis.tests import datafiles as data
+   >>> u = mda.Universe(data.TPR, data.TRR, format="CHEMFILES")
+   >>> print(u.trajectory)
+   <ChemfilesReader ~/anaconda3/envs/mda3/lib/python3.8/site-packages/MDAnalysisTests/data/adk_oplsaa.trr with 10 frames of 47681 atoms>
+
+You can then use the :class:`~MDAnalysis.core.universe.Universe` as usual while chemfiles
+is handling the I/O transparently in the background.
+
+`chemfiles`_ can also *write* a number of formats for which there are no Writers in
+MDAnalysis. For example, to write a mol2 file::
+
+   >>> u = mda.Universe(data.mol2_ligand)
+   >>> with mda.Writer("ligand.mol2", format="CHEMFILES") as W:
+   ...     W.write(u.atoms)
+
+
+
 
 Classes
 -------
 
+Classes to read and write files using the `chemfiles`_ library. This library
+provides C++ implementation of multiple formats readers and writers.
+
 .. autoclass:: ChemfilesReader
 
 .. autoclass:: ChemfilesWriter
 
 .. autoclass:: ChemfilesPicklable
+
+Helper functions
+----------------
+
+.. autodata:: MIN_CHEMFILES_VERSION
+.. autodata:: MAX_CHEMFILES_VERSION
+.. autofunction:: check_chemfiles_version
+
 """
 from distutils.version import LooseVersion
 import warnings
@@ -60,14 +100,20 @@ class MockTrajectory:
     HAS_CHEMFILES = True
 
 
+#: Lowest version of chemfiles that is supported
+#: by MDAnalysis.
 MIN_CHEMFILES_VERSION = LooseVersion("0.9")
+#: Lowest version of chemfiles that is *not supported*
+#: by MDAnalysis.
 MAX_CHEMFILES_VERSION = LooseVersion("0.10")
 
 
 def check_chemfiles_version():
-    """Check an appropriate Chemfiles is available
+    """Check if an appropriate *chemfiles* is available
 
-    Returns True if a usable chemfiles version is available
+    Returns ``True`` if a usable chemfiles version is available,
+    with :data:`MIN_CHEMFILES_VERSION` <= version < 
+    :data:`MAX_CHEMFILES_VERSION`
 
     .. versionadded:: 1.0.0
     """
@@ -108,13 +154,11 @@ def __init__(self, filename, chemfiles_format="", **kwargs):
         chemfiles_format : str (optional)
             if *filename* was a string, use the given format name instead of
             guessing from the extension. The `list of supported formats
-            <formats>`_ and the associated names is available in chemfiles
+            <formats>`_ and the associated names is available in the chemfiles
             documentation.
         **kwargs : dict
             General reader arguments.
 
-
-        .. _formats: http://chemfiles.org/chemfiles/latest/formats.html
         """
         if not check_chemfiles_version():
             raise RuntimeError("Please install Chemfiles > {}"
@@ -252,8 +296,6 @@ def __init__(self, filename, n_atoms=0, mode="w", chemfiles_format="", topology=
         **kwargs : dict
             General writer arguments.
 
-
-        .. _formats: http://chemfiles.org/chemfiles/latest/formats.html
         """
         if not check_chemfiles_version():
             raise RuntimeError("Please install Chemfiles > {}"