diff --git a/CHANGELOG.md b/CHANGELOG.md index 1bdfc78..cf9762f 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/docs/README.md b/docs/README.md index 337be3a..1149412 100644 --- a/docs/README.md +++ b/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`). diff --git a/docs/source/index.rst b/docs/source/index.rst index 4540722..c14f24c 100644 --- a/docs/source/index.rst +++ b/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 diff --git a/mdaencore/similarity.py b/mdaencore/similarity.py index 8be3c97..1999b75 100644 --- a/mdaencore/similarity.py +++ b/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` """