Update docs formatting

Author: Rob-Welch

.readthedocs.yaml

@@ -16,4 +16,5 @@ python:
     - method: pip
       path: .
       extra_requirements:
-        - docs
+        - docs
+        - myst-parser

docs/source/Developer-Notes.rst docs/source/Developer-Notes.mddocs/source/Developer-Notes.rst renamed to docs/source/Developer-Notes.md

@@ -3,8 +3,7 @@ Preparing structure files for simulation with prepmd
 
 Note: When running `prepmd`, we recommend using .mmCif files where possible. The .pdb file format is deprecated and is provided for legacy compatibility only.
 
-prepmd workflow
----------------
+## prepmd workflow
 Steps in the `prepmd` workflow:
 * The structure file(s) are downloaded (if not supplied) into a working directory. `prepmd` automatically infers the file format from the file extension of the input/output files.
 * `prepmd` extracts the sequence from the residues in the PDB directly and compares them to a reference sequence. By default this is the sequence described in the SEQRES entries of the structure file. The two sequences are alligned and [MODELLER](https://salilab.org/modeller/) is used to fill in the missing residues.
@@ -15,41 +14,31 @@ Steps in the `prepmd` workflow:
 * Finally, [OpenMM](https://openmm.org/) is used to perform a test minimisation and simulation. This step ensures that the resulting file is ready for simulation and that there are no steric clashes. If the minimisation or test simulation fails, it will be retried with OpenMM's variable langevin integrator. In testing, this has successfully minimised structure files with high clash scores.
 * The final, mimimised structure file will be written out. Note: if ligands are present, the non-minimised structure will be written instead - this is to allow the user to choose which ligand files to include in their final structure, which can be minimised using `runmd`.
 
-prepmd command-line reference
------------------------------
+## prepmd command-line reference
 * Use `prepmd --help` for a full list of parameters. 
 
-Worked examples
----------------
+## Worked examples
 
-Using a local structure file
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+### Using a local structure file
  `prepmd --structure 6xov_input.pdb 6xov 6xov_processed.pdb`. You still need to supply a PDB code, as some of the file formats used by prepmd require one to be present. The code doesn't have to be a 'real' PDB code, e.g. 'AAAA' will work fine. When using this setting, the input and output files must be in the same format * prepmd doesn't perform implicit conversions!
 
-Generate multiple structure files
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+### Generate multiple structure files
 `prepmd 6xov 6xov_processed.pdb -n 5` will generate 5 candidate structures and select the best one as determined by MODELLER's internal metrics. Alternatively, `prepmd 6xov 6xov_processed.pdb -n 5 -em 22281 --contour 0.01` will download EMD-22281, the EMDB entry associated with 6XOV, and score the generated models based on their agreement with the EM density map (using the iterative closest point algorithm). The -em setting can also point to a map file. Note: this won't do anything without a MODELLER license key.
 
-Use refined structures from PDB-REDO
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+### Use refined structures from PDB-REDO
 `prepmd 1cbs 1cbs_processed.pdb --redo` will download a refined structure from PDB-REDO, if it is available. Note: not all PDB entries have corresponding PDB-REDO entries.
 
-Use your own alignments and sequences to fill missing loops
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+### Use your own alignments and sequences to fill missing loops
 By default, `prepmd` will read missing residues from the pdb/mmcif SEQRES records, attempt to align the missing residues with the currently present residues, and then build missing loops with MODELLER. You can manually provide an aligned FASTA file containing the the complete and incomplete sequences with `--fasta`.  You can also ask prepmd to get the sequence data from UNIPROT instead, with `--download`, though this is not recommended, as the raw sequence data can be substantially different from the PDB and cause the alignment to fail.
 
-Handling ligands
-^^^^^^^^^^^^^^^^
+### Handling ligands
 By default, `prepmd` strips all HETATMS records from structure files. To keep these files, run prepmd with `--hetatms`, which will strip the HETATMS records from the structure file and write each residue to its own SDF file. The co-ordinates inside the SDF files correspond to the co-ordinates of the ligands in the structure file, so the ligands can be added back into the original structure easily. `prepmd` uses [rdkit](https://www.rdkit.org/) to add hydrogens and correct the geometry of small molecules.
 
-Adding hydrogens
-^^^^^^^^^^^^^^^^
+### Adding hydrogens
 Use the `--ph` flag to set the pH to use when adding hydrogens in pdbfixer, e.g. `prepmd 6xov 6xov.pdb -ph 7.0`. For more control, you can output a PQR file by running `prepmd 6xov 6xov.pdb -ph 7.0 --pqr 6xov.pqr`. As with ligands, this file won't be minimised, as that would remove the charges and radii added by PDB2PQR, though you this file can still be minimised with runmd after the fact.
 
-Working directory
-^^^^^^^^^^^^^^^^^
+### Working directory
 By default, `prepmd` will leave intermediate files in a randomly-named temporary directory. You can set the name of this directory: `prepmd --wdir 6xov_temp 6xov 6xov.cif`.
 
-Other notes
-^^^^^^^^^^^
-Warning: `prepmd`'s output does not contain any of the metadata found in the original pdb. This is an intentional omission - a lot of metadata (pdb REMARKs, for example) is specific to the indexing of atoms, residues and chains in that file, which are usually changed by prepmd.
+### Other notes
+Warning: `prepmd`'s output does not contain any of the metadata found in the original pdb. This is an intentional omission - a lot of metadata (pdb REMARKs, for example) is specific to the indexing of atoms, residues and chains in that file, which are usually changed by prepmd.

docs/source/Installation.rst docs/source/Installation.mddocs/source/Installation.rst renamed to docs/source/Installation.md

@@ -0,0 +1,15 @@
+Python API
+==========
+
+``prepmd`` is also accessible via a Python API:
+
+```python
+from prepmd.add_modeller_license import setup_license
+setup_license("<your license key>")  # only needs to be done once
+
+from prepmd.prep import prep
+prep("6xov", "6xov.cif", "working_dir")
+
+from prepmd.run import run
+run("6xov.cif", traj_out="traj.xtc")
+```

docs/source/Prep-Structure.rst docs/source/Prep-Structure.mddocs/source/Prep-Structure.rst renamed to docs/source/Prep-Structure.md

@@ -1,51 +1,43 @@
 Running MD simulations with runmd
 =================================
 
-Steps in the `runmd` workflow:
+## runmd workflow
 * Validate user input - runmd will attempt to infer the best parameters and halt if incompatible/impossible settings are used.
 * Create an OpenMM system object. If small molecules are present, `runmd` will also load the [OpenFF](https://openforcefield.org/) Sage small molecule force field.
 * If there is explicit solvent, set up the simulation box and solvate the system.
 * If the run is a metadynamics run, setup bias variables and forces using [openmmtools](https://openmmtools.readthedocs.io/en/stable/).
 * Attempt to minimise and run the simulation with OpenMM. If the run/minimisation crashes, the numerical integrator will automatically be switched to the variable langevin integrator and the simulation will be restarted.
 * If the run is a metadynamics run, and the metadynamics collective variables aren't minimised, the simulation will restart.
 
-runmd command-line reference
-============================
+## runmd command-line reference
 * Use `runmd --help` for a full list of parameters. 
 
-Output files
-------------
+## Example usage
+
+### Output files
 `runmd 6xov_processed.cif -o structure_minimised.cif --traj_out traj.xtc --md_steps 5000` writes out a trajectory file and a structure file (mmcif or pdb) containing the minimised system. If the system has been solvated, this structure file also contains the solvent molecules. The trajectory can be written in DCD or XTC format, which is detected from the filename. The xtc format results in smaller files but with less precision.
 
-Explicit solvent
-----------------
+### Explicit solvent
 `runmd structure.cif -o structure_minimised.cif --traj_out traj.xtc --md_steps 500 --step 10 -solv tip4pew` will run a simulation with the tip4pew solvent. tip3p, tip4pew and spce are supported. By default, simulations run with an implicit solvent equivalent to AMBER's `igb=8` option.
 
-Temperature and pressure
-------------------------
+### Temperature and pressure
 The default settings result in a rather loose coupling to the heat bath. You can change this with the `-f` or `--friction` argument, which specified the friction coefficient coupling the system to the heat bath. Running a simulation with explicit solvent will result in tighter coupling. You can also add pressure coupling with `--pressure 1.0` (for 1 bar).
 
-Change force field
-------------------
+### Change force field
 `runmd structure.cif -o structure_minimised.cif --traj_out traj.xtc --md_steps 500 --step 50 -ff amber14` runs with amber14. charmm36, amoeba, amber14 and amber19 are available, with charmm36 being the default. The force field is one of the most important MD parameters, and the best force field to use is normally system-dependent.
 
-Equilibrate only side chains:
------------------------------
+### Equilibrate only side chains:
 `runmd structure.cif -o structure_minimised.cif --fix_backbone -solv tip4pew --notest` will fix the backbone in place and only equilibrate side chains.
 
-Add ligands
------------
+### Add ligands
 `runmd structure.cif -l LIG.sdf -ff amber14` runs a simulation with a ligand. You can add multiple ligands by using the `-l` argument multiple times. `runmd` supports small molecules using openff's Sage force field, which has limited compatibility with other force fields and solvent models, so ligand simulations only run with the amber14 force field and explicit solvent. By default, ligand simulations also run with a much smaller timestep. Note: runmd will try to infer the ligand name, but you can pass `-ln` for each ligand to specify the name manually. This string will be used to identify the ligand in the output topology file, so if it can't be found, the ligand will just be listed as 'UNK'.
 
-Create a morph trajectory
--------------------------
+### Create a morph trajectory
 `runmd pre.cif -m post.cif -o minimised_out.pdb`  will create a trajectory that smoothly transitions between the structures in pre.cif and post.cif. This trajectory is created using openmmtools' metadynamics features. The metadynamics run applies arbitrary biasing forces to perform the transition, so this should only be used for visualisation/illustration, and may not represent the underlying physics and biology.
 If you have two files for the same structure which aren't aligned (e.g. they have slightly different starting/ending residues), you can trim the ends to align them: `aligntogether pre.cif post.cif pre_cropped.cif post_cropped.cif`
 
-Numerical integrators
----------------------
+### Numerical integrators
 Set the numerical integrator with the `-i` flag. This can be either `VariableLangevinIntegrator` or `LangevinMiddleIntegrator`. By default, `runmd` will attempt to use the latter, and fall back to the former if the simulation becomes numerically unstable. The parameter `--minimise-err` sets the error tolerance or the variable langevin integrator. Its value is arbitrary * 0.001 is a good starting point, increasing it will make the simulation run faster at the expense of accuracy.
 
-Other settings
---------------
-By default, `runmd` will try to select the most optimal nonbonded interaction method, but this can be overridden with `-nb` or `--nonbonded`, which can be one of `PME`, `CutoffPeriodic`, or `CutoffNonPeriodic`. Similarly, it will constrain the length of all bonds involving a hydrogen atom, which can allow for longer timesteps at the cost of some accuracy. This can be disabled by setting `-c None` or `--constraints None`. This setting is also disabled if the backbone is fixed.
+### Other settings
+By default, `runmd` will try to select the most optimal nonbonded interaction method, but this can be overridden with `-nb` or `--nonbonded`, which can be one of `PME`, `CutoffPeriodic`, or `CutoffNonPeriodic`. Similarly, it will constrain the length of all bonds involving a hydrogen atom, which can allow for longer timesteps at the cost of some accuracy. This can be disabled by setting `-c None` or `--constraints None`. This setting is also disabled if the backbone is fixed.

docs/source/Python-API.md

@@ -21,6 +21,7 @@
     "sphinx.ext.extlinks",
     "nbsphinx",
     "sphinx_copybutton",
+    "myst_parser",
 ]
 
 autosummary_generate = True