Merge pull request #568 from peastman/docs

Fixes to documentation

docs-source/CMakeLists.txt

@@ -84,15 +84,19 @@ ENDIF(DOXYGEN_EXECUTABLE)
 SET(SPHINX_BUILD_DIR "${CMAKE_BINARY_DIR}/sphinx-docs/")
 FILE(MAKE_DIRECTORY "${SPHINX_BUILD_DIR}")
 
+FILE(GLOB_RECURSE USER_GUIDE_FILES ${CMAKE_CURRENT_SOURCE_DIR}/usersguide/*)
+FILE(GLOB_RECURSE DEVELOPER_GUIDE_FILES ${CMAKE_CURRENT_SOURCE_DIR}/developerguide/*)
 ADD_CUSTOM_COMMAND(
     OUTPUT "${SPHINX_BUILD_DIR}/userguide/latex/OpenMMUsersGuide.pdf"
     COMMAND "${CMAKE_MAKE_PROGRAM}" BUILDDIR="${SPHINX_BUILD_DIR}/userguide" OPENMM_VERSION="${OPENMM_MAJOR_VERSION}.${OPENMM_MINOR_VERSION}" latexpdf
+    DEPENDS ${USER_GUIDE_FILES}
     WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/usersguide"
     COMMENT "Generating PDF user guide"
 )
 ADD_CUSTOM_COMMAND(
     OUTPUT "${SPHINX_BUILD_DIR}/developerguide/latex/OpenMMDeveloperGuide.pdf"
     COMMAND "${CMAKE_MAKE_PROGRAM}" BUILDDIR="${SPHINX_BUILD_DIR}/developerguide" OPENMM_VERSION="${OPENMM_MAJOR_VERSION}.${OPENMM_MINOR_VERSION}" latexpdf
+    DEPENDS ${DEVELOPER_GUIDE_FILES}
     WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/developerguide"
     COMMENT "Generating PDF developer guide"
 )
@@ -103,14 +107,16 @@ ADD_CUSTOM_TARGET(sphinxpdf
 ADD_CUSTOM_COMMAND(
     OUTPUT "${SPHINX_BUILD_DIR}/userguide/html/index.html"
     COMMAND "${CMAKE_MAKE_PROGRAM}" BUILDDIR="${SPHINX_BUILD_DIR}/userguide" OPENMM_VERSION="${OPENMM_MAJOR_VERSION}.${OPENMM_MINOR_VERSION}" html
+    DEPENDS ${USER_GUIDE_FILES}
     WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/usersguide"
-    COMMENT "Generating PDF user guide"
+    COMMENT "Generating HTML user guide"
 )
 ADD_CUSTOM_COMMAND(
     OUTPUT "${SPHINX_BUILD_DIR}/developerguide/html/index.html"
     COMMAND "${CMAKE_MAKE_PROGRAM}" BUILDDIR="${SPHINX_BUILD_DIR}/developerguide" OPENMM_VERSION="${OPENMM_MAJOR_VERSION}.${OPENMM_MINOR_VERSION}" html
+    DEPENDS ${DEVELOPER_GUIDE_FILES}
     WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/developerguide"
-    COMMENT "Generating PDF developer guide"
+    COMMENT "Generating HTML developer guide"
 )
 ADD_CUSTOM_TARGET(sphinxhtml
     DEPENDS "${SPHINX_BUILD_DIR}/userguide/html/index.html" "${SPHINX_BUILD_DIR}/developerguide/html/index.html"

docs-source/sphinx/autonumber.py

@@ -43,6 +43,7 @@ def doctree_resolved(app, doctree, docname):
             chapter = sectionNumbers[chapter.attributes['ids'][0]][0]
             if chapter != lastChapter:
                 index = {}
+                nextNumber = 1
             newNode = Text('%s %d-%d' % (category, chapter, nextNumber))
             lastChapter = chapter
         else:

docs-source/usersguide/library.rst

@@ -20,11 +20,11 @@ high level interface for running simulations.  This layer is targeted at
 computational biologists or other people who want to run simulations, and who
 may or may not be programmers.
 
-Part I of this guide focused on the application layer and described how to run
+The first part of this guide focused on the application layer and described how to run
 simulations with it.  We now turn to the lower level libraries.  We will assume
 you are a programmer, that you are writing your own applications, and that you
-want to add simulation features to those applications.  Part II of this guide
-describes how to do that with OpenMM.
+want to add simulation features to those applications.  The following chapters
+describe how to do that with OpenMM.
 
 How to get started
 ==================
@@ -42,7 +42,8 @@ License
 ========
 
 Two different licenses are used for different parts of OpenMM.  The public API,
-the low level API, and the reference platform are all distributed under the MIT
+the low level API, the reference platform, the CPU platform, and the application
+layer are all distributed under the MIT
 license.  This is a very permissive license which allows them to be used in
 almost any way, requiring only that you retain the copyright notice and
 disclaimer when distributing them.
@@ -425,12 +426,18 @@ Get the OpenMM source code
 You will also need the OpenMM source code before building OpenMM from source.
 To download and unpack OpenMM source code:
 
-#. Browse to https://simtk.org/home/openmm/.
+#. Browse to https://simtk.org/home/openmm.
 #. Click the "Downloads" link in the navigation bar on the left side.
 #. Download OpenMM<Version>-Source.zip, choosing the latest version.
 #. Unpack the zip file.  Note the location where you unpacked the OpenMM source
    code.
 
+Alternatively, if you want the most recent development version of the code rather
+than the version corresponding to a particular release, you can get it from
+https://github.com/SimTk/openmm.  Be aware that the development code is constantly
+changing, may contain bugs, and should never be used for production work.  If
+you want a stable, well tested version of OpenMM, you should download the source
+code for the latest release as described above.
 
 Other Required Software
 =======================
@@ -540,10 +547,10 @@ There are several variables that can be adjusted in the CMake interface:
   install OpenMM.
 
 
-Configure (press “\ :code:`c`\ ”) again.  Adjust any variables that cause an
+Configure (press “c”) again.  Adjust any variables that cause an
 error.
 
-Continue to configure (press “\ :code:`c`\ ”) until no starred/red CMake
+Continue to configure (press “c”) until no starred/red CMake
 variables are displayed.  Congratulations, you have completed the configuration
 step.
 
@@ -566,7 +573,7 @@ Windows
 Mac and Linux
 =============
 
-* Press :code:`g` to generate the Makefile.
+* Press “g” to generate the Makefile.
 * If CMake does not exit automatically, press “q” to exit.
 
 
@@ -1321,9 +1328,11 @@ to change the build environment.
                                             double stepSizeInFs, 
                                             std::string& platformName);
     static void          myStepWithOpenMM(MyOpenMMData*, int numSteps);
-    static void          myGetOpenMMState(MyOpenMMData*, bool 
-    wantEnergy,double& time, double& energy, 
-                               MyAtomInfo atoms[]);
+    static void          myGetOpenMMState(MyOpenMMData*,
+                                          bool wantEnergy,
+                                          double& time,
+                                          double& energy, 
+                                          MyAtomInfo atoms[]);
     static void          myTerminateOpenMM(MyOpenMMData*);
     
     
@@ -3544,7 +3553,7 @@ Hamiltonian is given by
 
 
 .. math::
-   H=\sum _{k=1}^{n}\left(\frac{{p}_{{k}^{2}}}{2m}+E({q}_{k})+\frac{m({k}_{B}Tn)^{2}}{2h^{2}}({q}_{k}-{q}_{k-1})^{2}\right)
+   H=\sum _{k=1}^{n}\left(\frac{{p}_{{k}^{2}}}{2m}+E({q}_{k})+\frac{m({k}_{B}Tn)^{2}}{2\hbar^{2}}({q}_{k}-{q}_{k-1})^{2}\right)
 
 
 This Hamiltonian resembles that of a system of classical ring polymers where
@@ -3560,7 +3569,7 @@ needed to converge a calculation can be estimated using\ :cite:`Markland2008`\
 
 
 .. math::
-   n>\frac{h\omega_{max}}{{k}_{B}T}
+   n>\frac{\hbar\omega_{max}}{{k}_{B}T}
 
 
 where :math:`\omega_{max}` is the highest frequency in the problem.  For example, for