doc updates following review

Author: richardjgowers

docs/cookbook/creating_mappings.rst renamed to docs/cookbook/creating_atom_mappings.rst

@@ -1,9 +1,11 @@
-Creating mappings
-=================
+.. _Creating Atom Mappings:
 
-With your chemical models loaded and defined into two :class:`.ChemicalSystem` objects,
-we can now proceed to defining how components in these systems correspond.
-``Mapping`` objects are used to defined how ``Component`` objects from different systems are related.
+Creating Atom Mappings
+======================
+
+Once your :ref:`data has been loaded<Loading Molecules>`
+we can now proceed to defining how Components in these Systems correspond.
+``Mapping`` objects are used to defined how ``Component`` objects from different :class:`ChemicalSystems` are related.
 This guide will show how this concept applies to the case of a pair of ligands we wish to transform between.
 
 Generating Mappings
@@ -43,7 +45,7 @@ This is how we can create a mapping between two ligands:
 
 The first and second ligand molecules put into the ``suggest_mappings`` method
 are then henceforth referred to as ``componentA`` and ``componentB``.
-The correspondence of atoms in these two components is then given via the `.componentA_to_componentB` attribute,
+The correspondence of atoms in these two components is then given via the ``.componentA_to_componentB`` attribute,
 which returns a dictionary of integers.
 Keys in this dictionary refer to the indices of atoms in the "A" molecule,
 while the corresponding values refer to indices of atoms in the "B" molecule.

docs/cookbook/index.rst

@@ -6,7 +6,7 @@ This will include various how-to guides.
 .. toctree::
 
     loading_molecules
-    creating_mappings
+    creating_atom_mappings
     dumping_transformation
 
 

docs/cookbook/loading_molecules.rst

@@ -1,3 +1,5 @@
+.. _Loading Molecules:
+
 Loading your data into ChemicalSystems
 ======================================
 
@@ -52,14 +54,21 @@ As these types of structures are typically stored inside sdf files, there is a `
     smc = openfe.SmallMoleculeComponent.from_sdf_file('file.sdf')
 
 
+.. note::
+   The ``from_sdf_file`` method will only read the first molecule in a multi-molecule MolFile.
+   To load multiple molcules, use RDKit's ``Chem.SDMolSupplier`` to iterate over the contents,
+   and create a ``SmallMoleculeComponent`` from each.
+
+
 Loading proteins
 ----------------
 
 Proteins are handled using an :class:`openfe.ProteinComponent`.
 Like ``SmallMoleculeComponent``, these are based upon RDKit Molecules,
 however these are expected to have the `MonomerInfo` struct present on all atoms.
 This struct contains the residue and chain information and is essential to apply many popular force fields.
-A "protein" here is considered as the fully modelled entire biological assembly, i.e. all chains and structural waters.
+A "protein" here is considered as the fully modelled entire biological assembly,
+i.e. all chains and structural waters and ions etc.
 
 To load a protein, use the :func:`openfe.ProteinComponent.from_pdb_file` or :func:`openfe.ProteinComponent.from_pdbx_file` classmethod
 
@@ -78,8 +87,9 @@ Unlike the previously detailed Components, this does not have any explicit molec
 but instead represents the way that the overall system will be solvated.
 This information is then interpreted inside the ``Protocol`` when solvating the system.
 
-By default, this solvent is water.  The positive and negative ion can be defined, as well as the ion concentration
-which must be specified along with the unit.
+By default, this solvent is water with 0.15 M NaCl salt.
+All parameters; the positive and negative ion as well as the ion concentration (which must be specified along with the unit)
+can be freely defined.
 
 .. code::