doc fixes (#51)

* Fixes #25, #50
* Updated docs README
* Updated CHANGELOG
* Added linking with core docs
* pep8

CHANGELOG.md

@@ -28,7 +28,7 @@ The rules for this file:
 - wheel deployment workflow (#22)
 
 ### Fixed
-- documentation fixes (#13, #18, #49)
+- documentation fixes (#13, #18, #49, #51)
 
 ### Changed
 <!-- Changes in existing functionality -->

docs/README.md

@@ -1,24 +1,29 @@
 # Compiling mdaencore's Documentation
 
 The docs for this project are built with [Sphinx](http://www.sphinx-doc.org/en/master/).
-To compile the docs, first ensure that Sphinx and the ReadTheDocs theme are installed.
-
+To compile the docs, first ensure the correct environment is installed, as defined in the `docs/requirements.yaml`
 
 ```bash
-conda install sphinx sphinx_rtd_theme 
+conda env update --file=requirements.yaml
 ```
 
+If this is in a separate environment to your main development environment, you will need to reinstall `mdaencore`, from the parent directory, into this environment.
+Alternatively, you can update your development environment with the above yaml by providing the name of that development environment, though it's generally a better idea to keep them separate.
+
+``conda env update -n dev_env --file=requirements.yaml``
+
+Once the documentation tools and `mdaencore` are installed, you can use the `Makefile` in this directory to compile static HTML pages by
 
-Once installed, you can use the `Makefile` in this directory to compile static HTML pages by
 ```bash
 make html
 ```
 
-The compiled docs will be in the `_build` directory and can be viewed by opening `index.html` (which may itself 
-be inside a directory called `html/` depending on what version of Sphinx is installed).
+The compiled docs will be in the `_build` directory and can be viewed by opening `index.html` (which may itself be inside a directory called `html/` depending on what version of Sphinx is installed).
 
 
-A configuration file for [Read The Docs](https://readthedocs.org/) (readthedocs.yaml) is included in the top level of the repository. To use Read the Docs to host your documentation, go to https://readthedocs.org/ and connect this repository. You may need to change your default branch to `main` under Advanced Settings for the project.
+A configuration file for [Read The Docs](https://readthedocs.org/) (readthedocs.yaml) is included in the top level of the repository.
+To use Read the Docs to host your documentation, go to https://readthedocs.org/ and connect this repository.
+You may need to change your default branch to `main` under Advanced Settings for the project.
 
 If you would like to use Read The Docs with `autodoc` (included automatically) and your package has dependencies, you will need to include those dependencies in your documentation yaml file (`docs/requirements.yaml`).
 

docs/source/index.rst

@@ -19,7 +19,7 @@ ensembles described in :footcite:p:`LindorffLarsen2009`. The implementation and
 are described in :footcite:p:`Tiberti2015`.
 
 The module includes facilities for handling ensembles and trajectories through
-the :class:`Universe` class, performing clustering or dimensionality reduction
+the :class:`~MDAnalysis.core.universe.Universe` class, performing clustering or dimensionality reduction
 of the ensemble space, estimating multivariate probability distributions from
 the input data, and more. ENCORE can be used to compare experimental and
 simulation-derived ensembles, as well as estimate the convergence of

mdaencore/similarity.py

@@ -30,11 +30,11 @@
 described in :footcite:p:`Tiberti2015`.
 
 The module includes facilities for handling ensembles and trajectories through
-the :class:`Universe` class, performing clustering or dimensionality reduction
-of the ensemble space, estimating multivariate probability distributions from
-the input data, and more. ENCORE can be used to compare experimental and
-simulation-derived ensembles, as well as estimate the convergence of
-trajectories from time-dependent simulations.
+the :class:`~MDAnalysis.core.universe.Universe` class, performing clustering
+or dimensionality reduction of the ensemble space, estimating multivariate
+probability distributions from the input data, and more. ENCORE can be used to
+compare experimental and simulation-derived ensembles, as well as estimate the
+convergence of trajectories from time-dependent simulations.
 
 ENCORE includes three different methods for calculations of similarity measures
 between ensembles implemented in individual functions:
@@ -1045,13 +1045,13 @@ def ces(ensembles,
     --------
     To calculate the Clustering Ensemble similarity, two ensembles are
     created as Universe object using a topology file and two trajectories. The
-    topology- and trajectory files used are obtained from the MDAnalysis
-    test suite for two different simulations of the protein AdK.
-    To use a different clustering method, set the parameter clustering_method
-    (Note that the sklearn module must be installed). Likewise, different parameters
-    for the same clustering method can be explored by adding different
-    instances of the same clustering class.
-    Here the simplest case of just two instances of :class:`Universe` is illustrated:
+    topology- and trajectory files used are obtained from the MDAnalysis test
+    suite for two different simulations of the protein AdK. To use a different
+    clustering method, set the parameter clustering_method (Note that the
+    sklearn module must be installed). Likewise, different parameters for the
+    same clustering method can be explored by adding different instances of
+    the same clustering class. Here the simplest case of just two instances
+    of :class:`~MDAnalysis.core.universe.Universe` is illustrated:
 
         >>> from MDAnalysis import Universe
         >>> import mdaencore as encore
@@ -1325,8 +1325,8 @@ def dres(ensembles,
     To use a different dimensional reduction methods, simply set the
     parameter dimensionality_reduction_method. Likewise, different parameters
     for the same clustering method can be explored by adding different
-    instances of the same method  class.
-    Here the simplest case of comparing just two instances of :class:`Universe` is
+    instances of the same method  class. Here the simplest case of comparing
+    just two instances of :class:`~MDAnalysis.core.universe.Universe` is
     illustrated:
 
         >>> from MDAnalysis import Universe
@@ -1341,7 +1341,7 @@ def dres(ensembles,
 
     In addition to the quantitative similarity estimate, the dimensional
     reduction can easily be visualized, see the ``Example`` section in
-    :mod:`mdaencore.dimensionality_reduction.reduce_dimensionality``
+    :mod:`mdaencore.dimensionality_reduction.reduce_dimensionality`
 
     """