organize documentation

docs/src/contributions.md

@@ -1,3 +1,7 @@
+```@meta
+CollapsedDocStrings = true
+```
+
 # [Atomic and group contributions](@id contributions)
 
 One of the interesting features of Minimum-Distance distributions is
@@ -37,8 +41,16 @@ the contributions of every type of atom of the solute and the solvent.
 These contributions can be retrieved using the `contributions` function,
 with the `SoluteGroup` and `SolventGroup` selectors.
 
-For example, if the MDDF of water (solvent) relative to a solute was computed,
-and water has atom names `OH2, H1, H2`, one can retrieve the contributions
+```@docs
+contributions
+SolventGroup
+SoluteGroup
+```
+
+### Example: computing the oxygen contributions of water
+
+Here we show the MDDF of water (solvent) relative to a solute.
+Water molecules have atom names `OH2, H1, H2`, one can retrieve the contributions
 of the oxygen atom with:
 
 ```julia
@@ -140,8 +152,3 @@ hydrogen-bonding distances, but much less in general. Of course all
 selection options could be used, to obtain the contributions of specific
 types of residues, atoms, the backbone, the side-chains, etc. 
 
-## Reference functions
-
-```@docs
-contributions
-```

docs/src/multiple.md

@@ -1,3 +1,7 @@
+```@meta
+CollapsedDocStrings = true
+```
+
 # Working with multiple trajectories
 
 Very commonly, one has multiple trajectories of the same system, and we
@@ -53,6 +57,10 @@ second and third trajectories have 1000 frames each, the first
 trajectory will have a weight of 0.5 on the final results. The `merge` function
 can be used to merge previously merged results with new results as well.
 
+```@docs
+merge
+```
+
 !!! tip
 
     The names of the files and

docs/src/options.md

@@ -1,3 +1,7 @@
+```@meta
+CollapsedDocStrings = true
+```
+
 # [Options](@id options)
 
 There are some options to control what exactly is going to be computed

docs/src/results.md

@@ -181,9 +181,6 @@ The complete data available is:
 
 ```@docs
 Result
-load(::String, ::Type{Result})
-save(::String, ::Result)
-merge(::Vector{Result})
 overview(::Result)
 ComplexMixtures.Density
 ```

docs/src/save.md

@@ -1,3 +1,7 @@
+```@meta
+CollapsedDocStrings = true
+```
+
 # [Save and load results](@id save)
 
 Three functions serve the purpose of saving and loading the results
@@ -12,6 +16,10 @@ where `results` is the output data structure of the `mddf()`
 calculation, and `results.json` is the output file to be created. The
 file is written in `JSON` format, thus is not naturally human-readable.
 
+```@docs
+save(::String, ::Result)
+```
+
 ## Load saved data
 
 ```julia
@@ -20,6 +28,10 @@ results = load("results.json")
 The `load` function reads the output of the `save` function above,
 and restores the results data structure.
 
+```@docs
+load(::String, ::Type{Result})
+```
+
 ## Write data in a human-readable format
 
 If you Want the results to be written as simple ASCII tables such that

docs/src/selection.md

@@ -1,3 +1,6 @@
+```@meta
+CollapsedDocStrings = true
+```
 
 # [Solute and solvent selections](@id selections)
 
@@ -8,6 +11,15 @@ To construct a `AtomSelection` data structure, one needs to provide, at least,
 the (1-based) indices of the atoms that belong to the selection, and either
 the number of atoms of each molecule or the number of molecules in the selection.
 
+```@docs
+AtomSelection
+AtomSelection(::Any)
+```
+
+Alternatively, and more practically, atom selections defined by the `PDBTools`
+package, which can interface with the selection syntax of `VMD`, can be used,
+as described in the following sections.
+
 ## Using the PDBTools package
 
 The [PDBTools](https://m3g.github.io/PDBTools) package helps the construction of 
@@ -157,17 +169,8 @@ julia> result = mddf(trajectory_file, solute, solvent, Options(bulk_range=(8.0,
 julia> acidic_residue_contributions = contributions(result, SoluteGroup("acidic residues"))
 ```
 
-## Reference functions
-
-```@autodocs
-Modules = [ComplexMixtures]
-Pages = ["AtomSelection.jl"]
+```@docs
+atom_group
+atom_group_name
+atom_group_names
 ```
-
-
-
-
-
-
-
-

src/AtomSelection.jl

@@ -189,15 +189,14 @@ The structure can be initialized in different ways:
 
 1. Initialize the structure providing a vector of PDBTools.Atom(s).
 
-```
+
     AtomSelection(
         atoms::AbstractVector{<:PDBTools.Atom}; 
         nmols::Integer = 0, 
         natomspermol::Integer = 0,
         group_atom_indices::Union{Nothing,Vector{<:Vector{<:Int}}} = nothing,
         group_names::Vector{<:AbstractString} = String[]
     ) 
-```
 
 The indices of the atoms will be retrived from the
 indices of the atoms as defined in the PDB file, thus the PDB file must correspond to the same
@@ -236,15 +235,14 @@ julia> length(atom_group_names(atsel))
 
 2. Lower level: initialize the structure providing the index of atoms and groups.
 
-```
+
     AtomSelection(
         indices::AbstractVector{<:Integer};
         nmols::Int = 0,
         natomspermol::Int = 0,
         group_atom_indices::Union{Nothing,AbstractVector{<:AbstractVector{<:Int}}} = nothing,
         group_names::AbstractVector{<:AbstractString} = String[]
     )
-```
 
 Construct an AtomSelection structure from the most low-level information: the index of atoms and groups.