Reorganize docs

RELEASE.md

@@ -1,18 +1,62 @@
-# Creating new MDT project releases
+# Whenever commiting changes anywhere
+
+Make SURE that you've run `set_filters.sh` at the project base. This will make sure that you don't accidentally commit any `ipynb` output fields into the repository. You can check to make sure the filters are working by running `git diff` on any notebook file that has output in it: all `output` and `metadata` fields should remain blank.
+
+# Creating a Pull Request
 
 These instructions generally apply to [Autodesk/molecular-design-toolkit](https://github.com/Autodesk/molecular-design-toolkit),
 [Autodesk/py-cloud-compute-cannon](https://github.com/Autodesk/py-cloud-compute-cannon), and [Autodesk/notebook-molecular-visualization](https://github.com/Autodesk/notebook-molecular-visualization).
 
-This is only for project maintainers - everyone else should use PRs.
+1. Group all changes in a single branch.
+1. Run tests in `moldesign/_tests` with `py.test -n NCORES` where `NCORES` is the number of jobs to run simultanously.
+2. Create a pull-request for the appropriate branch in Autodesk/molecular-design-toolkit
+
+
+# Maintainers: Accepting a PR
+
+Work can be merged into `master` or a feature branch, as appropriate. Don't merge broken code
+into master, but it doesn't need to be totally production-ready either: only releases (below)
+are considered "stable".
+
+1. Review the code.
+1. Make sure that there's appropriate functional tests.
+1. Run all tests. They don't all *necessarily* need to pass, but you need to undertand why  what's passing and what's not.
+1. Run any example notebooks that might be affected by the PR.
+
+
+# Maintainers: Creating a new release
+
+Decide on the new version number (using [semantic versioning](http://semver.org/)).
+
+Everything here is HIGHLY PRELIMINARY!!! This will be a lot easier once Travis/Jenkins is up.
+
+1. Make sure all changes have been PR'd into master
+1. Check out a clean copy of master
+1. Run `check-manifest` at project root to make sure the distribution will include the necessary files.
+1. Increment the `default_version_tag` field in `moldesign.compute.config`, and commit the change
+1. Tag your local branch with the release number: `git tag [version]` (note: delete this tag with `git tag rm [version]` if you need to abort the release)
+4. Build new docker images: `cd docker_images; ./dockermake.py --all --repo docker.io/Autodesk/moldesign: --tag [version]`
+1. Confirm that all tests are passing *with and without* locally installed dependencies (pyscf, openbabel, etc)
+1. Confirm that all tutorial and example notebooks run without errors.
+
+If this is all succesfull - you're ready to make it public.
+
+1. Push docker images to cloud: `cd docker_images; ./dockermake.py --all --push --repo docker.io/Autodesk/moldesign: --tag [version]`
+4. `python setup.py register -r pypi`
+5. `python setup.py sdist upload -r pypi`
+1. `git push origin master --tags`
+
+The final step is the point of no return - you'll need to prep a new release if you discover a problem. Before that, you can undo
+what you've done by deleting your release off of PyPI and DockerHub.
+
+
+
+# Maintainers: updating docs
 
-Everything here is HIGHLY PRELIMINARY!!! This will change dramatically once Jenkins or Travis is up.
+Documentation is NOT coupled to the package releases; docs tend to get updated continuously.
 
-1. Push changes or merge PR into dev branch and check out a clean copy.
-1. Test it.
-1. Run `check-manifest` at project root. (Repeat steps 1-3 until this checks out OK)
-1. [MDT only] - update/push dockerfiles and image URLs in `moldesign.compute.configuration`
-2. Pull-request into master
-3. Tag master branch with new release number
-4. In repo root. `python setup.py register -r pypi`
-5. In repo root, `python setup.py sdist upload -r pypi`
-6. [MDT only] Run `cd docs; make html` and push contents of `_build/html` to the gh-pages branch.
+1. In the `master` branch, update the version numbers in `docs/conf.py`
+1. Run `cd docs; make clean; make html`. 
+1. In a separate directory, check out a fresh copy of the repo and run `git checkout gh-pages`
+1. Copy the contents of `[master branch]/docs/_build/html` into the root of the `gh-pages` branch.
+1. Commit your changes to the `gh-pages` branch and push them back to GitHub.

docs/api/atoms.rst

@@ -0,0 +1,6 @@
+============
+Atom objects
+============
+
+.. autoclass:: moldesign.Atom
+   :members:

docs/biomolecule.rst

@@ -0,0 +1,55 @@
+Biomolecular structure
+======================
+
+
+
+Primary structure
+-----------------
+**Class documentation:** :class:`moldesign.Chain`, :class:`moldesign.Residue`
+
+Biomolecules also contain primary structure information such as :class:`Chains <moldesign.Chain>`
+and :class:`Residues <moldesign.Residue>`. Chains can be accessed by name OR by index:
+
+   >>> chain1 = molecule.chains['A']
+   >>> chain2 = molecule.chains[0]
+   >>> chain1 is chain2
+   True
+
+Each chain contains :class:`residues <moldesign.Residue>`. In a chain, residues can similarly be
+accessed through a flat list or by name:
+
+   >>> res0 = molecule.residues[0]
+   >>> resA = molecule.chains['A'].residues['PRO1']
+   >>> res0 is resA
+   True
+
+A flat list of all residues in a molecule is also available at `molecule.residues`.
+
+
+
+Biomolecular assemblies
+-----------------------
+Many biomolecules in the PDB only contain a subset of the total biomolecular structure - the
+remaining parts of the structure can be generated via `symmetry transformations <http://pdb101.rcsb.org/learn/guide-to-understanding-pdb-data/biological-assemblies>`_.
+
+When you read in such a structure, MDT will issue a warning.
+
+   >>> mol = mdt.from_pdb('3FPP')
+   WARNING: This PDB file contains the following biomolecular assemblies:
+   WARNING: Assembly "1": 3 copies of chains A, B
+   WARNING: Use ``mdt.build_assembly([molecule],[assembly_name])`` to build one of the above assemblies
+
+To create the full assembly, run
+   >>> assembly = mdt.build_assembly(mol,"1")
+   >>> assembly.draw()
+
+   .. image:: img/howdoi_pdb_assm.png
+
+Note:
+   Only PDB-formatted files are currently supported for biomolecular assemblies - MMCif support
+   is in progress.
+
+
+
+
+

docs/conf.py

@@ -69,12 +69,12 @@
 #source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'contents'
+master_doc = 'index'
 
 # General information about the project.
 project = u'Molecular Design Toolkit'
 copyright = u'2016 Autodesk Research'
-author = u'Aaron Virshup, Dion Amago, Malte Tinnus (Bio/Nano Research Group, Autodesk)'
+author = u'Aaron Virshup, Dion Amago, Justin McCandless, Malte Tinnus (Bio/Nano Research Group, Autodesk)'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -83,9 +83,9 @@
 
 import moldesign
 # The short X.Y version.
-version = moldesign.__version__
+version = '0.7'
 # The full version, including alpha/beta/rc tags.
-release = moldesign.__version__
+release = '0.7.3'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/creating_and_converting.rst

@@ -1,9 +1,64 @@
-Creating and converting molecules
----------------------------------
+Creating molecules
+==================
 
 
-From other objects
-==================
+From names and ids
+------------------
+You can use an IUPAC name:
+
+   >>> import moldesign as mdt
+   >>> benzene = mdt.from_name('benzene')
+   >>> caffeine = mdt.from_name('1,3,7-Trimethylpurine-2,6-dione')
+
+or a `SMILES string <https://en.wikipedia.org/wiki/Simplified_molecular-input_line-entry_system>`_
+
+   >>> benzene = mdt.from_smiles('c1ccccc1')
+   >>> caffeine = mdt.from_smiles('CN1C=NC2=C1C(=O)N(C(=O)N2C)C')
+
+
+To download a biomolecular structure from the `Protein DataBank <http://www.rcsb.org/>`_, you can use
+
+   >>> hiv_protease = mdt.from_pdb('3AID')
+
+DNA helices can be generated from a genetic sequence:
+
+   >>> bdna = mdt.build_dna_helix('ACTG')
+
+
+From files
+----------
+MDT supports most common molecular formats via ``moldesign.read``. In most cases, the format can be inferred from the filename. Files compressed with `gz` or `bz2` can be read as well.
+
+   >>> benzene = mdt.read('benzene.sdf')
+   >>> caffeine = mdt.read('caffeine.xyz')
+   >>> lsd = mdt.read('lsd.mol2.gz')
+   >>> hiv_protease = mdt.read('3aid.pdb.bz2')
+   >>> zika_capsid = mdt.read('5ire.cif')
+
+In addition, any pickled python object can be read in with this function - files with ``pickle``, ``pkl``, and ``P`` are recognized as pickle files:
+   >>> saved_mol = mdt.read('molecule_1.pickle')
+   >>> saved_atom = mdt.read('atom_2.pkl.gz')
+   >>> saved_trajectory = mdt.read('traj.P.bz2')
+
+
+From strings
+------------
+File content in strings or file-like objects can be read as well, but the format needs to be explicitly specified.
+
+   >>> water_str = """ 3
+   >>>                 water xyz file
+   >>>                 O          0.98285        0.07497        0.04837
+   >>>                 H          0.70400        0.94631        0.36769
+   >>>                 H          1.95074        0.11856        0.06434 """
+   >>> water = mdt.read(water_str, format='xyz')
+   >>>
+   >>> import StringIO
+   >>> water_filelike = StringIO.StringIO(water_str)
+   >>> molecule = mdt.read(water_filelike, format='xyz')
+
+
+From other molecules
+--------------------
 You can create a new molecule from any collection of atoms.
 
 For instance, a list of atoms:
@@ -18,3 +73,13 @@ Or even a list of molecules, atoms, and residues:
    >>> dmso = mdt.from_name('dmso')
    >>> cobalt_atom = mdt.Atom(symbol='Co')
    >>> complex = mdt.Molecule([protein, dmso, cobalt_atom])
+
+
+From other python packages
+--------------------------
+MDT's interfaces allow it to import objects from a variety of other molecular modeling packages, including;
+
+- `OpenBabel <http://openbabel.org/>`_ / `Pybel <https://openbabel.org/docs/dev/UseTheLibrary/Python_Pybel.html>`_ : ``mdt.interfaces.pybel_to_mdt(pybel_molecule)``
+- `OpenMM <http://openmm.org/>`_: ``mdt.interfaces.openmm_topology_to_mdt(openmm_topology)``
+- `BioPython <http://biopython.org/wiki/Biopython>`_: ``mdt.interfaces.biopython_to_mdt(biopython_pdb_structure)``
+- `PdbFixer <https://github.com/pandegroup/pdbfixer>`_: ``mdt.interfaces.pdbfixer_to_mdt(pdbfixer_object)``

docs/dynamics.rst

@@ -0,0 +1,17 @@
+Molecular dynamics
+==================
+
+Protein MD
+----------
+
+WIP
+
+Small molecule MD
+-----------------
+
+WIP
+
+Quantum chemical potentials
+---------------------------
+
+WIP

docs/features.rst

@@ -6,22 +6,13 @@ Molecular Design Toolkit Features
 
 
 
-Simulation methods
-------------------
-
-Energy models
-^^^^^^^^^^^^^
-
-**Methods**
-
- - :meth:`Molecule.calculate` Calculate molecular properties using the assigned energy model
-
- - :meth:`Molecule.minimize` Perform an energy minimization using the assigned energy model
-
-**Classical**
+Molecular Mechanics
+-------------------
 
  - :class:`models.Forcefield` Generic Forcefield energy model (automatically chosen implementation)
 
+ - :class:`models.GAFF` Amber force field for small organic molecules
+
  - :class:`models.OpenMMEnergyModel` OpenMM energy kernel for Amber/CHARMM-like forcefields
 
  - :class:`models.SanderEnergyModel` Sander energy kernel (from AmberTools) for Amber/CHARMM-like forcefields
@@ -30,11 +21,15 @@ Energy models
 
  - :class:`models.HarmonicOscillator` A 1-D Harmonic oscillator centered at x=0 (for testing and toy models)
 
-**Quantum**
 
- - :class:`models.RHF` Generic restricted Hartree-Fock (automatically chosen implementation)
+Quantum Chemistry
+-----------------
+
+ - :class:`models.RHF` Restricted Hartree-Fock (automatically chosen implementation)
 
- - :class:`models.DFT` Generic density functional theories (automatically chosen implementation)
+ - :class:`models.DFT` Density functional theories (automatically chosen implementation)
+
+ - :class:`models.CASSCF` Complete-active space MCSCF (automatically chosen implementation)
 
  - :class:`models.Semiempirical` Generic semiempirical theories (automatically chosen implementation)
 
@@ -43,8 +38,8 @@ Energy models
  - :class:`models.SQM` SQM semi-empirical energy kernel (from AmberTools), includes implementations for a large number of semiempirical models, including MNDO, AM1, PM3, PM6, DFTB
 
 
-Integrators
-^^^^^^^^^^^
+Molecular Dynamics
+^^^^^^^^^^^^^^^^^^
 
  - :class:`integrators.VelocityVerlet` Generic Velocity Verlet dynamics (automatically chosen implementation)
 
@@ -57,8 +52,8 @@ Integrators
  - :class:`integrators.SurfaceHopping` Multi-state surface hopping dynamics using fewest switched. Implementation: internal.
 
 
-Interactive Widgets
--------------------
+Interactive visualization
+-------------------------
 
  - :class:`viewer.Configurator` Automatically generates user interfaces for configuring simulations
 
@@ -107,8 +102,8 @@ Simulation results are stored in numpy arrays with an explicit unit system based
  - :meth:`Trajectory.time` :meth:`Trajectory.potential_energy` :meth:`Trajectory.kinetic_temperature` ``...`` - Return timeseries of times, energies, temperatures, etc. over the course of a trajectory
 
 
-Conversions
------------
+Interfaces
+----------
 
 **Files and databases**