Major update and organisation of docs.

Author: andrewtarzia

docs/source/_templates/module.rst

@@ -14,28 +14,29 @@
    {% endif %}
    {% endblock %}
 
-   {% block functions %}
-   {% if functions %}
-   .. rubric:: {{ _('Functions') }}
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
 
    .. autosummary::
       :toctree:
+      :template: class.rst
       :nosignatures:
-   {% for item in functions %}
+   {% for item in classes %}
       {{ item }}
    {%- endfor %}
    {% endif %}
    {% endblock %}
 
-   {% block classes %}
-   {% if classes %}
-   .. rubric:: {{ _('Classes') }}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
 
    .. autosummary::
       :toctree:
-      :template: class.rst
       :nosignatures:
-   {% for item in classes %}
+   {% for item in functions %}
       {{ item }}
    {%- endfor %}
    {% endif %}

docs/source/analysis.rst

@@ -0,0 +1,56 @@
+
+Analysis
+========
+
+A package of the classes for analysing molecules in :mod:`.CGExplore`.
+
+.. toctree::
+  :maxdepth: 1
+
+  Analysis module <_autosummary/cgexplore.analysis>
+
+Geometry
+--------
+
+To analyse the geometry of CG molecules (including size and pore metrics),
+see:
+
+.. toctree::
+  :maxdepth: 1
+
+  GeomMeasure <_autosummary/cgexplore.analysis.GeomMeasure>
+
+To calculate torsions:
+
+.. toctree::
+  :maxdepth: 1
+
+  get_dihedral <_autosummary/cgexplore.analysis.get_dihedral>
+
+Shape
+-----
+
+We have a series of functions (moving into one class
+:class:`cgexplore.analysing.ShapeMeasure`) for interfacing with
+`Shape <https://www.iqtc.ub.edu/uncategorised/program-for-the-stereochemical-analysis-of-molecular-fragments-by-means-of-continous-shape-measures-and-associated-tools/>`_.
+I recommend using what is in this class:
+
+.. toctree::
+  :maxdepth: 1
+
+  ShapeMeasure <_autosummary/cgexplore.analysis.ShapeMeasure>
+
+Old utility functions (will be removed one day):
+
+.. toctree::
+  :maxdepth: 1
+
+  fill_position_matrix_molecule <_autosummary/cgexplore.analysis.fill_position_matrix_molecule>
+  fill_position_matrix <_autosummary/cgexplore.analysis.fill_position_matrix>
+  get_shape_molecule_byelement <_autosummary/cgexplore.analysis.get_shape_molecule_byelement>
+  get_shape_molecule_ligands <_autosummary/cgexplore.analysis.get_shape_molecule_ligands>
+  get_shape_molecule_nodes <_autosummary/cgexplore.analysis.get_shape_molecule_nodes>
+  known_shape_vectors <_autosummary/cgexplore.analysis.known_shape_vectors>
+  test_shape_mol <_autosummary/cgexplore.analysis.test_shape_mol>
+
+

docs/source/cgexplore.rst

@@ -41,5 +41,5 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "furo"
+html_theme = "sphinx_rtd_theme"
 html_static_path = ["_static"]

docs/source/conf.py

@@ -0,0 +1,50 @@
+First Paper Example
+===================
+
+.. attention::
+
+    This page is very much underdevelopment.
+
+.. important::
+
+  **Warning**: If you have a CUDA-capable GPU and attempt to use CUDA in the
+  first example, you may get `NaN` errors due to the torsion restriction for
+  angles at 180 degrees, which cause problematic forces. This will be handled
+  in future versions of the code. And logically, I would suggest removing the
+  torsion restriction for those angles. The `platform` can be handled through
+  this argument in `build_building_blocks` and `build_populations`, which I
+  currently set to `None`, meaning `OpenMM` will decide for itself.
+
+
+:mod:`.CGExplore` is a library that can be used very broadly on many systems.
+However, my first usage on the systematic modelling of cage molecules is
+described here and the code is available in the directory `first_paper_example`.
+This code should reproduce the data in `10.1039/D3SC03991A <https://doi.org/10.1039/D3SC03991A>`_.
+However, as :mod:`.CGExplore` is updated, some deviations may occur.
+With each pull request a test is run as a GitHub Action connected to this
+`repository <https://github.com/andrewtarzia/cg_model_test>`_. This ensures that
+the results obtained for a subset of the original data set do not change with
+changes to this library. Additionally, the naming convention has changed and
+forcefield `.xml` files should provide the appropriate information for mapping
+angles to models.
+
+.. note::
+    The main change is the use of `Atomlite` databasing!
+
+
+I recommend installing the :mod:`.CGExplore` with the following instructions
+and then using the example directory in a separate repository or code base of
+your own.
+
+Download the source code from `first_paper_example - presubmission` release
+from `Releases <https://github.com/andrewtarzia/CGExplore/releases>`_ instead
+of the `main` repository. Then follow the instructions on the main page.
+
+
+The workflow:
+
+* `generate_XX.py` generates cage structures for different topology sets
+* `env_set.py` sets a specific environment for file outputs
+* `plot_XX.py` produces images and figures, and performs analysis
+
+

docs/source/first_paper_example.rst

@@ -0,0 +1,89 @@
+Forcefields
+===========
+
+A package of defining the forcefields used in `CGExplore`.
+All of these forcefields interface with `OpenMM`.
+
+.. toctree::
+  :maxdepth: 1
+
+  Forcefields module <_autosummary/cgexplore.forcefields>
+
+
+There is a lot of flexibility in how this code is used, however, `OpenMM`
+requires a :class:`cgexplore.forcefields.ForcedSystem`.
+
+.. note::
+
+   Actually use :class:`cgexplore.forcefields.AssignedSystem` or
+   :class:`cgexplore.forcefields.MartiniSystem`.
+
+
+
+Libraries
+---------
+
+These classes allow the user to automatically define a series of forcefields
+that vary some parameters in a systematic way in a brute-force combinatorial
+way.
+
+.. toctree::
+  :maxdepth: 1
+
+  ForceFieldLibrary <_autosummary/cgexplore.forcefields.ForceFieldLibrary>
+  MartiniForceFieldLibrary <_autosummary/cgexplore.forcefields.MartiniForceFieldLibrary>
+
+
+Forcefields
+-----------
+
+Classes defining the forcefield before it is assigned to any molecule. This
+provides an interface for the user to set the target terms of the forcefield
+that can then be assigned to any molecule.
+
+.. toctree::
+  :maxdepth: 1
+
+  ForceField <_autosummary/cgexplore.forcefields.ForceField>
+  MartiniForceField <_autosummary/cgexplore.forcefields.MartiniForceField>
+
+
+Forced systems
+--------------
+
+Here, the user creates the object that interfaces between a forcefield and an
+`OpenMM` simulation.
+
+.. toctree::
+  :maxdepth: 1
+
+  ForcedSystem <_autosummary/cgexplore.forcefields.ForcedSystem>
+  AssignedSystem <_autosummary/cgexplore.forcefields.AssignedSystem>
+  MartiniSystem <_autosummary/cgexplore.forcefields.MartiniSystem>
+
+
+Custom forces
+-------------
+
+.. toctree::
+  :maxdepth: 1
+
+  cosine_periodic_angle_force <_autosummary/cgexplore.forcefields.cosine_periodic_angle_force>
+  custom_excluded_volume_force <_autosummary/cgexplore.forcefields.custom_excluded_volume_force>
+
+
+Utilities
+---------
+
+.. toctree::
+  :maxdepth: 1
+
+  angle_between <_autosummary/cgexplore.forcefields.angle_between>
+  unit_vector <_autosummary/cgexplore.forcefields.unit_vector>
+  MartiniTopology <_autosummary/cgexplore.forcefields.MartiniTopology>
+  get_martini_mass_by_type <_autosummary/cgexplore.forcefields.get_martini_mass_by_type>
+
+
+.. toctree::
+  :maxdepth: 1
+

docs/source/forcefields.rst

@@ -3,7 +3,13 @@
    :caption: CGExplore
    :maxdepth: 2
 
-   cgexplore <cgexplore>
+   Analysis <analysis>
+   Forcefields <forcefields>
+   Molecular <molecular>
+   Optimisation <optimisation>
+   Terms <terms>
+   Utilities <utilities>
+   First Paper Example <first_paper_example>
 
 .. toctree::
   :hidden:
@@ -12,38 +18,111 @@
 
   Modules <modules>
 
-============
+
 Introduction
-============
+------------
 
 | GitHub: https://www.github.com/andrewtarzia/CGExplore
 
 
-:mod:`.CGExplore` is a Python library for doing something...
-
+:mod:`.CGExplore` is a Python library for for working with
+coarse-grained models.
 
+The library is built off of `stk <https://stk.readthedocs.io/en/stable/>`_,
+which comes with the pip install.
 
+.. important::
+  **Warning**: This package is still very much underdevelopment and many changes
+  are expected.
 
 Installation
 ------------
 
-TODO
+To get :mod:`.CGExplore`, you need to follow these steps:
+
+Clone :mod:`.CGExplore` from `here <https://github.com/andrewtarzia/CGExplore>`_
+
+Create a `conda` or `mamba` environment::
+
+  $ mamba create -n NAME python=3.11
+
+Activate the environment::
+
+  $ conda activate NAME
+
+
+From :mod:`.CGExplore` directory, install pip environment::
+
+  $ pip install .
+
+or for development, use `just <https://github.com/casey/just>`_ to install a
+dev environment with::
+
+  $ just dev
+
+
+Install `OpenMM` `docs <https://openmm.org/>`_::
+
+  $ mamba install openmm
+
+or::
+
+  $ conda install -c conda-forge openmm
+
+
+Install `openmmtools` `docs <https://openmmtools.readthedocs.io/en/stable/gettingstarted.html>`_::
+
+  $ mamba install openmmtools
+
+or::
+
+  $ conda config --add channels omnia --add channels conda-forge
+  $ conda install openmmtools
+
+
+Then, update directory structure in `env_set.py` if using example code.
+
+The library implements some analysis that uses `Shape 2.1`. Follow the
+instructions to download and installed at
+`Shape <https://www.iqtc.ub.edu/uncategorised/program-for-the-stereochemical-analysis-of-molecular-fragments-by-means-of-continous-shape-measures-and-associated-tools/>`_
 
 
 Examples
 --------
 
-TODO
+
+The main series of examples are in `First Paper Example`_. In that page you
+will find all the information necessary to reproduce the work in
+`10.1039/D3SC03991A <https://doi.org/10.1039/D3SC03991A>`_
+
+With each pull request a test is run as a GitHub Action connected to this
+`repository <https://github.com/andrewtarzia/cg_model_test>`_.
+This ensures that the results obtained for a subset of the original data set do
+not change with changes to this library.
+
+.. note::
+
+  `cg_model_test <https://github.com/andrewtarzia/cg_model_test>`_ is a good
+  example of usage too!
+
+
+New works done with :mod:`.CGExplore`:
+
+* TBC.
 
 
 Acknowledgements
 ----------------
 
-I developed much of this code when working in the Pavan group (https://www.gmpavanlab.com/).
+This work was completed during my time as a postdoc, and then research fellow
+in the Pavan group at PoliTO (https://www.gmpavanlab.com/).
 
 Indices and tables
 ------------------
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
+
+
+.. _`First Paper Example`: first_paper_example.html