Merge pull request #863 from openforcefield/how-to-docs

Document how to build the docs

docs/developing.rst

@@ -149,25 +149,25 @@ ParameterHandler
         - ``postprocess_system``: operates identically to ``create_force``, but is run after each ParameterHandlers' ``create_force`` has already been called.
           The default implementation of this method simply does nothing, and should suffice for most developers.
 
-.. TODO : fill in the modular components below
-
-ParameterType
-
-   ToolkitRegistry
-
-       ``ToolkitRegistry.from_object``  / ``ToolkitRegistry.from_smiles`` / ``OpenEyeToolkitWrapper.from_openeye`` / ``RDKitToolkitWrapper.from_rdkit``
-        - These methods are a bit strange because they are effectively classmethods for ``FrozenMolecule`` and ``Molecule`` subclasses.
+ToolkitRegistry
+    ``ToolkitRegistry.from_object``  / ``ToolkitRegistry.from_smiles`` / ``OpenEyeToolkitWrapper.from_openeye`` / ``RDKitToolkitWrapper.from_rdkit``
+          These methods are a bit strange because they are effectively classmethods for ``FrozenMolecule`` and ``Molecule`` subclasses.
           In `PR #583 <https://github.com/openforcefield/openff-toolkit/pull/583>`_, jaimergp raised a concern that effectively boils down to "if I subclass ``Molecule`` into a new class, ``MyMol``, then I expect ``MyMol.from_rdkit`` to return an instance of ``MyMol``, not ``Molecule``.
           However, before this PR, methods like ``ToolkitRegistry.from_smiles`` didn't have any way to know what type of object they should return, and instead always returned ``Molecule`` objects.
           So as of  `PR #583 <https://github.com/openforcefield/openff-toolkit/pull/583>`_, ToolkitRegistry methods that produce a Molecule must take a private parameter, ``_cls``, indicating the type of object to return.
           This parameter should be of type ``type`` and should subclass ``FrozenMolecule``, or otherwise expose ``Molecule._add_atom``, ``._add_bond``, ``.add_conformer``, and ``.partial_charges``.
 
 
-   Molecule.to_X
 
-   Molecule.from_X
+.. TODO : fill in the modular components below, and clarify ToolkitRegistry above
+
+    ParameterType
+
+    Molecule.to_X
+
+    Molecule.from_X
 
-   Force field directories
+    Force field directories
 
 
 .. TODO : fill in the sections below
@@ -224,19 +224,60 @@ Setting up a development environment
 
 .. code-block:: shell
 
-    $ # Create a conda environment with the Open Force Field toolkit and its dependencies
-    $ conda create --name openff-dev -c conda-forge -c openeye openff-toolkit openeye-toolkits
-    $ conda activate openff-dev
-    $ # Remove (only) the toolkit and replace it with a local install
-    $ conda remove --force openff-toolkit
-    $ git clone https://github.com/openforcefield/openff-toolkit
-    $ cd openff-toolkit
-    $ pip install -e .
+    # Create a conda environment with the Open Force Field toolkit and its dependencies
+    conda create --name openff-dev -c conda-forge -c openeye openff-toolkit openeye-toolkits
+    conda activate openff-dev
+    # Remove (only) the toolkit and replace it with a local install
+    conda remove --force openff-toolkit
+    git clone https://github.com/openforcefield/openff-toolkit
+    cd openff-toolkit
+    pip install -e .
 
 3. Obtain and store Open Eye license somewhere like ``~/.oe_license.txt``.
    Optionally store the path in environmental variable ``OE_LICENSE``, i.e. using a command like ``echo
    "export OE_LICENSE=/Users/yournamehere/.oe_license.txt" >> ~/.bashrc``
 
+Building the Docs
+'''''''''''''''''
+
+The documentation is composed of two parts, a hand-written user guide and an auto-generated API
+documentation.
+Both are compiled by Sphinx, and can be automatically served and regenerated on changes with sphinx-autobuild.
+Documentation for released versions is available at `ReadTheDocs <https://open-forcefield-toolkit.readthedocs.io/en/latest/>`_.
+ReadTheDocs also builds the documentation for each Pull Request opened on GitHub and keeps the output for 90 days.
+
+To add the documentation dependencies to your existing ``openff-dev`` Conda environment:
+
+.. code-block:: shell
+
+    # Add the documentation requirements to your Conda environment
+    conda env update --name openff-dev --file docs/environment.yml
+    conda install --name openff-dev -c conda-forge sphinx-autobuild
+
+To build the documentation from scratch:
+
+.. code-block:: shell
+
+    # Build the documentation
+    # From the openff-toolkit root directory
+    conda activate openff-dev
+    cd docs
+    make html
+    # Documentation can be found in docs/_build/html/index.html
+
+To watch the source directory for changes and automatically rebuild the documentation and refresh your browser:
+
+.. code-block:: shell
+
+    # Host the docs on a local HTTP server and rebuild when a source file is changed
+    # Works best when the docs have already been built
+    # From the openff-toolkit root directory
+    conda activate openff-dev
+    sphinx-autobuild docs docs/_build/html --watch openff
+    # Then navigate your web browser to http://localhost:8000
+
+
+
 
 Development Process
 """""""""""""""""""

docs/releasehistory.rst

@@ -17,6 +17,8 @@ Improved documentation and warnings
   Fixes `Issue #618 <https://github.com/openforcefield/openforcefield/issues/618>`_.
 - `PR #870 <https://github.com/openforcefield/openff-toolkit/pull/870>`_: Reorganised documentation
   to improve discoverability and allow future additions.
+- `PR #863 <https://github.com/openforcefield/openff-toolkit/pull/863>`_: Documented how to build
+  the docs in the developers guide.
 
 0.9.1 - Minor feature and bugfix release
 ----------------------------------------