Merge pull request #1238 from rmcgibbo/sphinx

New Sphinx API Docs

.travis.yml

@@ -81,7 +81,7 @@ matrix:
            CC=$CCACHE/clang
            CXX=$CCACHE/clang++
            DOCS_DEPLOY=true
-           CMAKE_FLAGS=""
+           CMAKE_FLAGS="-DOPENMM_GENERATE_API_DOCS=ON"
 
     - sudo: false
       python: 3.4
@@ -146,8 +146,8 @@ script:
   - # run all of the tests, making sure failures at this stage don't cause travis failures
   - python devtools/run-ctest.py -j2 --schedule-random --stop-time $CTEST_STOP_TIME
   - if [[ ! -z "${DOCS_DEPLOY}" && "${DOCS_DEPLOY}" = "true" ]]; then
-      pip install sphinx numpydoc;
-      make DoxygenApiDocs PythonApiDocs;
+      pip install sphinx sphinxcontrib-lunrsearch sphinxcontrib-autodoc_doxygen;
+      make C++ApiDocs PythonApiDocs;
       mkdir -p api-docs;
       mv api-python api-docs;
       mv api-c++ api-docs;

CMakeLists.txt

@@ -536,6 +536,8 @@ IF(OPENMM_BUILD_PYTHON_WRAPPERS)
 ENDIF(OPENMM_BUILD_PYTHON_WRAPPERS)
 
 
+
+
 #
 # Allow automated build and dashboard.
 #

cmake_modules/ApiDoxygen.cmake

-find_package(Doxygen)
-
-set(OPENMM_GENERATE_API_DOCS OFF CACHE BOOL "Whether to create API documentation using Doxygen")
-IF(DOXYGEN_FOUND)
-    SET(DOXY_CONFIG "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile")
-
-    CONFIGURE_FILE(${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile.in 
-          ${DOXY_CONFIG}
-          @ONLY )
-
-    ADD_CUSTOM_COMMAND(
-        OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/html/index.html"
-        COMMAND ${DOXYGEN_EXECUTABLE} ${DOXY_CONFIG}
-        WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
-        COMMENT "Generating API documentation using Doxygen"
-        SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile.in") 
-    ADD_CUSTOM_TARGET(DoxygenApiDocs 
-        COMMAND ${DOXYGEN_EXECUTABLE} ${DOXY_CONFIG}
-        WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
-        COMMENT "Generating API documentation using Doxygen"
-        SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile.in") 
-    FILE(MAKE_DIRECTORY "${PROJECT_BINARY_DIR}/html/")
-
-    IF(OPENMM_GENERATE_API_DOCS)
-        INSTALL(DIRECTORY "${PROJECT_BINARY_DIR}/html/"
-                DESTINATION "docs/api/")
-    ENDIF(OPENMM_GENERATE_API_DOCS)
-ELSE(DOXYGEN_FOUND)
-ENDIF(DOXYGEN_FOUND)
-

docs-source/CMakeLists.txt

@@ -3,77 +3,18 @@
 #
 
 find_package(Doxygen QUIET)
-mark_as_advanced(CLEAR DOXYGEN_EXECUTABLE)
+set(OPENMM_GENERATE_API_DOCS OFF CACHE BOOL "Whether to create API documentation using Doxygen")
+
 IF(DOXYGEN_EXECUTABLE)
     # Generate C++ API documentation
-
-    SET(DOXY_CONFIG_C++ "${CMAKE_BINARY_DIR}/DoxyfileC++")
-    CONFIGURE_FILE(${CMAKE_CURRENT_SOURCE_DIR}/DoxyfileC++.in 
-          ${DOXY_CONFIG_C++}
-          @ONLY )
-    FILE(GLOB_RECURSE OPENMM_INCLUDES "openmm/include/*.h")
-    FILE(GLOB_RECURSE OLLA_INCLUDES "olla/include/*.h")
-    ADD_CUSTOM_COMMAND(
-        OUTPUT "${CMAKE_BINARY_DIR}/api-c++/index.html"
-        COMMAND ${DOXYGEN_EXECUTABLE} ${DOXY_CONFIG_C++}
-        DEPENDS ${OPENMM_INCLUDES} ${OLLA_INCLUDES}
-        WORKING_DIRECTORY "${CMAKE_BINARY_DIR}"
-        COMMENT "Generating C++ API documentation using Doxygen")
-    ADD_CUSTOM_TARGET(C++ApiDocs 
-        DEPENDS "${CMAKE_BINARY_DIR}/api-c++/index.html"
-        COMMENT "Generating C++ API documentation using Doxygen"
-        SOURCES 
-            "${CMAKE_CURRENT_SOURCE_DIR}/DoxyfileC++.in"
-            ${OPENMM_INCLUDES}
-            ${OLLA_INCLUDES}
-    ) 
-    FILE(MAKE_DIRECTORY "${PROJECT_BINARY_DIR}/api-c++/")
-    INSTALL(DIRECTORY "${PROJECT_BINARY_DIR}/api-c++/"
-            DESTINATION "docs/api-c++/")
-    INSTALL(FILES "C++ API Reference.html"
-            DESTINATION "docs/")
-    ADD_CUSTOM_TARGET(DoxygenApiDocs
-        DEPENDS "${CMAKE_BINARY_DIR}/api-c++/index.html"
-        COMMENT "Generating C++ API documentation using Doxygen"
-        SOURCES 
-        "${CMAKE_CURRENT_SOURCE_DIR}/DoxyfileC++.in"
-        "${CMAKE_CURRENT_SOURCE_DIR}/DoxyfilePython.in"
-        ${OPENMM_INCLUDES}
-        ${OLLA_INCLUDES}
-    )
-    set(OPENMM_GENERATE_API_DOCS OFF CACHE BOOL "Whether to create API documentation using Doxygen")
     IF (OPENMM_GENERATE_API_DOCS)
-        SET_TARGET_PROPERTIES(DoxygenApiDocs PROPERTIES EXCLUDE_FROM_ALL FALSE)
+        ADD_SUBDIRECTORY(api-c++)
     ENDIF (OPENMM_GENERATE_API_DOCS)
 
     # Generate Python API documentation
-
-    IF (OPENMM_BUILD_PYTHON_WRAPPERS)
-        SET(DOXY_CONFIG_PYTHON "${CMAKE_BINARY_DIR}/DoxyfilePython")
-        CONFIGURE_FILE(${CMAKE_CURRENT_SOURCE_DIR}/DoxyfilePython.in 
-            ${DOXY_CONFIG_PYTHON}
-            @ONLY )
-        ADD_CUSTOM_COMMAND(
-            OUTPUT "${CMAKE_BINARY_DIR}/api-python/index.html"
-            COMMAND ${DOXYGEN_EXECUTABLE} ${DOXY_CONFIG_PYTHON}
-            DEPENDS RunSwig
-            WORKING_DIRECTORY "${CMAKE_BINARY_DIR}"
-            COMMENT "Generating Python API documentation using Doxygen")
-        ADD_CUSTOM_TARGET(PythonApiDocs 
-            DEPENDS "${CMAKE_BINARY_DIR}/api-python/index.html"
-            COMMENT "Generating Python API documentation using Doxygen"
-            SOURCES 
-                "${CMAKE_CURRENT_SOURCE_DIR}/DoxyfilePython.in"
-                ${OPENMM_INCLUDES}
-                ${OLLA_INCLUDES}
-        ) 
-        FILE(MAKE_DIRECTORY "${PROJECT_BINARY_DIR}/api-python/")
-        INSTALL(DIRECTORY "${PROJECT_BINARY_DIR}/api-python/"
-                DESTINATION "docs/api-python/")
-        INSTALL(FILES "Python API Reference.html"
-                DESTINATION "docs/")
-        ADD_DEPENDENCIES(DoxygenApiDocs PythonApiDocs)
-    ENDIF (OPENMM_BUILD_PYTHON_WRAPPERS)
+    IF (OPENMM_BUILD_PYTHON_WRAPPERS AND OPENMM_GENERATE_API_DOCS)
+        ADD_SUBDIRECTORY(api-python)
+    ENDIF (OPENMM_BUILD_PYTHON_WRAPPERS AND OPENMM_GENERATE_API_DOCS)
 ENDIF(DOXYGEN_EXECUTABLE)
 
 

docs-source/DoxyfilePython.in

-# Doxyfile 1.5.3
-
-#---------------------------------------------------------------------------
-# Project related configuration options
-#---------------------------------------------------------------------------
-DOXYFILE_ENCODING      = UTF-8
-PROJECT_NAME           = @PROJECT_NAME@
-PROJECT_NUMBER         = 
-OUTPUT_DIRECTORY       = 
-CREATE_SUBDIRS         = NO
-OUTPUT_LANGUAGE        = English
-BRIEF_MEMBER_DESC      = YES
-REPEAT_BRIEF           = YES
-ABBREVIATE_BRIEF       = 
-ALWAYS_DETAILED_SEC    = NO
-INLINE_INHERITED_MEMB  = NO
-FULL_PATH_NAMES        = NO
-STRIP_FROM_PATH        = 
-STRIP_FROM_INC_PATH    = 
-SHORT_NAMES            = NO
-JAVADOC_AUTOBRIEF      = YES
-QT_AUTOBRIEF           = NO
-MULTILINE_CPP_IS_BRIEF = NO
-DETAILS_AT_TOP         = YES
-INHERIT_DOCS           = YES
-SEPARATE_MEMBER_PAGES  = NO
-TAB_SIZE               = 4
-ALIASES                = 
-OPTIMIZE_OUTPUT_FOR_C  = NO
-OPTIMIZE_OUTPUT_JAVA   = YES
-BUILTIN_STL_SUPPORT    = NO
-CPP_CLI_SUPPORT        = NO
-DISTRIBUTE_GROUP_DOC   = YES
-SUBGROUPING            = YES
-#---------------------------------------------------------------------------
-# Build related configuration options
-#---------------------------------------------------------------------------
-EXTRACT_ALL            = YES
-EXTRACT_PRIVATE        = NO
-EXTRACT_STATIC         = NO
-EXTRACT_LOCAL_CLASSES  = YES
-EXTRACT_LOCAL_METHODS  = NO
-EXTRACT_ANON_NSPACES   = NO
-HIDE_UNDOC_MEMBERS     = NO
-HIDE_UNDOC_CLASSES     = NO
-HIDE_FRIEND_COMPOUNDS  = NO
-HIDE_IN_BODY_DOCS      = YES
-INTERNAL_DOCS          = NO
-CASE_SENSE_NAMES       = YES
-HIDE_SCOPE_NAMES       = YES
-SHOW_INCLUDE_FILES     = YES
-INLINE_INFO            = YES
-SORT_MEMBER_DOCS       = YES
-SORT_BRIEF_DOCS        = NO
-SORT_BY_SCOPE_NAME     = NO
-GENERATE_TODOLIST      = YES
-GENERATE_TESTLIST      = YES
-GENERATE_BUGLIST       = YES
-GENERATE_DEPRECATEDLIST= YES
-ENABLED_SECTIONS       = 
-MAX_INITIALIZER_LINES  = 30
-SHOW_USED_FILES        = YES
-SHOW_DIRECTORIES       = YES
-FILE_VERSION_FILTER    =
-SHOW_NAMESPACES        = NO
-SHOW_FILES             = NO
-SHOW_DIRECTORIES       = NO
-#---------------------------------------------------------------------------
-# configuration options related to warning and progress messages
-#---------------------------------------------------------------------------
-QUIET                  = NO
-WARNINGS               = YES
-WARN_IF_UNDOCUMENTED   = YES
-WARN_IF_DOC_ERROR      = YES
-WARN_NO_PARAMDOC       = NO
-WARN_FORMAT            = "$file:$line: $text    "
-WARN_LOGFILE           = 
-#---------------------------------------------------------------------------
-# configuration options related to the input files
-#---------------------------------------------------------------------------
-INPUT                  = "@CMAKE_BINARY_DIR@/python/simtk/openmm" "@CMAKE_BINARY_DIR@/python/simtk/openmm/app"
-INPUT_ENCODING         = UTF-8
-FILE_PATTERNS          = 
-RECURSIVE              = NO
-EXCLUDE                = 
-EXCLUDE_SYMLINKS       = NO
-EXCLUDE_PATTERNS       = 
-EXCLUDE_SYMBOLS        = SerializationNode SerializationProxy SwigPyIterator
-EXAMPLE_PATH           = 
-EXAMPLE_PATTERNS       = 
-EXAMPLE_RECURSIVE      = NO
-IMAGE_PATH             = 
-INPUT_FILTER           = "@PYTHON_EXECUTABLE@ @CMAKE_BINARY_DIR@/python/filterPythonFiles.py"
-FILTER_PATTERNS        = 
-FILTER_SOURCE_FILES    = YES
-#---------------------------------------------------------------------------
-# configuration options related to source browsing
-#---------------------------------------------------------------------------
-SOURCE_BROWSER         = NO
-INLINE_SOURCES         = NO
-STRIP_CODE_COMMENTS    = YES
-REFERENCED_BY_RELATION = YES
-REFERENCES_RELATION    = YES
-REFERENCES_LINK_SOURCE = YES
-USE_HTAGS              = NO
-VERBATIM_HEADERS       = YES
-#---------------------------------------------------------------------------
-# configuration options related to the alphabetical class index
-#---------------------------------------------------------------------------
-ALPHABETICAL_INDEX     = NO
-COLS_IN_ALPHA_INDEX    = 5
-IGNORE_PREFIX          = 
-#---------------------------------------------------------------------------
-# configuration options related to the HTML output
-#---------------------------------------------------------------------------
-GENERATE_HTML          = YES
-HTML_OUTPUT            = api-python
-HTML_FILE_EXTENSION    = .html
-HTML_HEADER            = 
-HTML_FOOTER            = 
-HTML_STYLESHEET        = 
-HTML_ALIGN_MEMBERS     = YES
-GENERATE_HTMLHELP      = NO
-HTML_DYNAMIC_SECTIONS  = YES
-CHM_FILE               = 
-HHC_LOCATION           = 
-GENERATE_CHI           = NO
-BINARY_TOC             = NO
-TOC_EXPAND             = NO
-DISABLE_INDEX          = NO
-ENUM_VALUES_PER_LINE   = 4
-GENERATE_TREEVIEW      = YES
-TREEVIEW_WIDTH         = 250
-#---------------------------------------------------------------------------
-# configuration options related to the LaTeX output
-#---------------------------------------------------------------------------
-GENERATE_LATEX         = NO
-LATEX_OUTPUT           = latex
-LATEX_CMD_NAME         = latex
-MAKEINDEX_CMD_NAME     = makeindex
-COMPACT_LATEX          = NO
-PAPER_TYPE             = a4wide
-EXTRA_PACKAGES         = 
-LATEX_HEADER           = 
-PDF_HYPERLINKS         = NO
-USE_PDFLATEX           = NO
-LATEX_BATCHMODE        = NO
-LATEX_HIDE_INDICES     = NO
-#---------------------------------------------------------------------------
-# configuration options related to the RTF output
-#---------------------------------------------------------------------------
-GENERATE_RTF           = NO
-RTF_OUTPUT             = rtf
-COMPACT_RTF            = NO
-RTF_HYPERLINKS         = NO
-RTF_STYLESHEET_FILE    = 
-RTF_EXTENSIONS_FILE    = 
-#---------------------------------------------------------------------------
-# configuration options related to the man page output
-#---------------------------------------------------------------------------
-GENERATE_MAN           = NO
-MAN_OUTPUT             = man
-MAN_EXTENSION          = .3
-MAN_LINKS              = NO
-#---------------------------------------------------------------------------
-# configuration options related to the XML output
-#---------------------------------------------------------------------------
-GENERATE_XML           = NO
-XML_OUTPUT             = xml
-XML_SCHEMA             = 
-XML_DTD                = 
-XML_PROGRAMLISTING     = YES
-#---------------------------------------------------------------------------
-# configuration options for the AutoGen Definitions output
-#---------------------------------------------------------------------------
-GENERATE_AUTOGEN_DEF   = NO
-#---------------------------------------------------------------------------
-# configuration options related to the Perl module output
-#---------------------------------------------------------------------------
-GENERATE_PERLMOD       = NO
-PERLMOD_LATEX          = NO
-PERLMOD_PRETTY         = YES
-PERLMOD_MAKEVAR_PREFIX = 
-#---------------------------------------------------------------------------
-# Configuration options related to the preprocessor   
-#---------------------------------------------------------------------------
-ENABLE_PREPROCESSING   = YES
-MACRO_EXPANSION        = YES
-EXPAND_ONLY_PREDEF     = YES
-SEARCH_INCLUDES        = YES
-INCLUDE_PATH           = 
-INCLUDE_FILE_PATTERNS  = 
-PREDEFINED             = 
-EXPAND_AS_DEFINED      = 
-SKIP_FUNCTION_MACROS   = YES
-#---------------------------------------------------------------------------
-# Configuration::additions related to external references   
-#---------------------------------------------------------------------------
-TAGFILES               = 
-GENERATE_TAGFILE       = "api-python/@PROJECT_NAME@DoxygenTagfile"
-ALLEXTERNALS           = NO
-EXTERNAL_GROUPS        = YES
-PERL_PATH              = /usr/bin/perl
-#---------------------------------------------------------------------------
-# Configuration options related to the dot tool   
-#---------------------------------------------------------------------------
-CLASS_DIAGRAMS         = YES
-MSCGEN_PATH            = /Applications/Doxygen.app/Contents/Resources/
-HIDE_UNDOC_RELATIONS   = YES
-HAVE_DOT               = NO
-CLASS_GRAPH            = YES
-COLLABORATION_GRAPH    = YES
-GROUP_GRAPHS           = YES
-UML_LOOK               = NO
-TEMPLATE_RELATIONS     = YES
-INCLUDE_GRAPH          = YES
-INCLUDED_BY_GRAPH      = YES
-CALL_GRAPH             = NO
-CALLER_GRAPH           = NO
-GRAPHICAL_HIERARCHY    = YES
-DIRECTORY_GRAPH        = YES
-DOT_IMAGE_FORMAT       = png
-DOT_PATH               = 
-DOTFILE_DIRS           = 
-DOT_GRAPH_MAX_NODES    = 50
-MAX_DOT_GRAPH_DEPTH    = 0
-DOT_TRANSPARENT        = NO
-DOT_MULTI_TARGETS      = NO
-GENERATE_LEGEND        = YES
-DOT_CLEANUP            = YES
-#---------------------------------------------------------------------------
-# Configuration::additions related to the search engine   
-#---------------------------------------------------------------------------
-SEARCHENGINE           = YES

docs-source/api-c++/CMakeLists.txt

+set(STAGING_OUTPUT_FILES "") # Will contain all required package files
+file(GLOB STAGING_INPUT_FILES RELATIVE "${CMAKE_CURRENT_SOURCE_DIR}"
+    "*.rst"
+    "*.rst.jinja2"
+    "*.py"
+    "_static/logo.png"
+)
+
+set(WRAPPER_DOXYGEN_DIR "${CMAKE_CURRENT_BINARY_DIR}/doxygen")
+file(MAKE_DIRECTORY "${WRAPPER_DOXYGEN_DIR}")
+
+configure_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
+    ${WRAPPER_DOXYGEN_DIR}/Doxyfile
+    @ONLY
+)
+
+add_custom_command(
+    OUTPUT "${WRAPPER_DOXYGEN_DIR}/xml/index.xml"
+    COMMAND "${DOXYGEN_EXECUTABLE}"
+    DEPENDS "${WRAPPER_DOXYGEN_DIR}/Doxyfile"
+    WORKING_DIRECTORY "${WRAPPER_DOXYGEN_DIR}"
+    COMMENT "Parsing OpenMM header files with Doxygen..."
+)
+
+foreach(INIT_FILE ${STAGING_INPUT_FILES})
+    set(infile "${CMAKE_CURRENT_SOURCE_DIR}/${INIT_FILE}")
+    set(outfile "${CMAKE_CURRENT_BINARY_DIR}/${INIT_FILE}")
+    add_custom_command(
+        OUTPUT "${outfile}"
+        COMMAND "${CMAKE_COMMAND}" -E copy_if_different "${infile}" "${outfile}"
+        DEPENDS "${infile}"
+        COMMENT "CMake-copying file ${infile} to ${outfile}")
+    set(STAGING_OUTPUT_FILES ${STAGING_OUTPUT_FILES} "${outfile}")
+endforeach(INIT_FILE ${STAGING_INPUT_FILES})
+
+add_custom_command(
+    OUTPUT  "${CMAKE_CURRENT_BINARY_DIR}/library.rst"
+    COMMAND "${PYTHON_EXECUTABLE}" "${CMAKE_CURRENT_BINARY_DIR}/render.py"
+            "${WRAPPER_DOXYGEN_DIR}/xml/"
+    DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/render.py"
+            "${CMAKE_CURRENT_BINARY_DIR}/library.rst.jinja2"
+            "${WRAPPER_DOXYGEN_DIR}/xml/index.xml"
+    )
+
+add_custom_command(
+    OUTPUT "${CMAKE_BINARY_DIR}/api-c++/index.html"
+    COMMAND "${PYTHON_EXECUTABLE}" -m sphinx . "${CMAKE_BINARY_DIR}/api-c++"
+    WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
+    DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/conf.py"
+            "${CMAKE_CURRENT_BINARY_DIR}/library.rst"
+            "${CMAKE_CURRENT_BINARY_DIR}/index.rst"
+            "${CMAKE_CURRENT_BINARY_DIR}/_static/logo.png"
+            "${WRAPPER_DOXYGEN_DIR}/xml/index.xml"
+)
+
+file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/api-c++/)
+add_custom_target(C++ApiDocs
+        DEPENDS ${CMAKE_BINARY_DIR}/api-c++/index.html)
+INSTALL(DIRECTORY "${CMAKE_BINARY_DIR}/api-c++/"
+        DESTINATION "docs/api-c++/")
+INSTALL(FILES "${CMAKE_CURRENT_SOURCE_DIR}/../C++ API Reference.html"
+        DESTINATION "docs/")

docs-source/api-c++/_static/logo.png

+../../api-python/_static/logo.png
\ No newline at end of file

docs-source/api-c++/conf.py

+import sys
+import os
+
+extensions = ['sphinx.ext.mathjax','sphinx.ext.autosummary',
+              'sphinx.ext.autodoc', 'sphinxcontrib.lunrsearch',
+              'sphinxcontrib.autodoc_doxygen']
+
+autosummary_generate = True
+autodoc_member_order = 'bysource'
+
+source_suffix = '.rst'
+master_doc = 'index'
+
+project = u'OpenMM'
+copyright = u'2015, Stanford University and the Authors'
+
+version = '@OPENMM_MAJOR_VERSION@.@OPENMM_MINOR_VERSION@'
+release = '@OPENMM_MAJOR_VERSION@.@OPENMM_MINOR_VERSION@'
+
+exclude_patterns = ['_build', '_templates']
+html_static_path = ['_static']
+templates_path = ['_templates']
+
+pygments_style = 'sphinx'
+
+html_theme = "alabaster"
+html_theme_options = {
+    'description': "High performance molecular simulation on GPUs",
+    'github_button': False,
+    # 'github_user': 'pandegroup',
+    # 'github_repo': 'openmm',
+    'logo_name': False,
+    'logo': 'logo.png',
+}
+html_sidebars = {
+    '**': [
+        'about.html',
+        'searchbox.html',
+        'navigation.html',
+    ]
+}
+
+doxygen_xml = "doxygen/xml"

docs-source/api-c++/index.rst

+OpenMM C++ API
+=================
+
+The C++ API provides information about the classes and methods available in OpenMM for C++ developers. The public API is based on a small number of classes.
+
+
+.. toctree::
+   :maxdepth: 2
+
+   library
+
+
+:cpp:class:`System <OpenMM::System>`\ : A System specifies generic properties of the system to be
+simulated: the number of particles it contains, the mass of each one, the size
+of the periodic box, etc.  The interactions between the particles are specified
+through a set of Force objects (see below) that are added to the System.  Force
+field specific parameters, such as particle charges, are not direct properties
+of the System.  They are properties of the Force objects contained within the
+System.
+
+:cpp:class:`Force <OpenMM::Force>`\ : The Force objects added to a System define the behavior of the
+particles.  Force is an abstract class; subclasses implement specific behaviors.
+The Force class is actually slightly more general than its name suggests.  A
+Force can, indeed, apply forces to particles, but it can also directly modify
+particle positions and velocities in arbitrary ways.  Some thermostats and
+barostats, for example, can be implemented as Force classes.  Examples of Force
+subclasses include :cpp:class:`HarmonincBondForce <OpenMM::HarmonincBondForce>`, :cpp:class:`NonbondedForce <OpenMM::NonbondedForce>`, and :cpp:class:`MonteCarloBarostat <OpenMM::MonteCarloBarostat>`.
+
+:cpp:class:`Context <OpenMM::Context>`\ : This stores all of the state information for a simulation:
+particle positions and velocities, as well as arbitrary parameters defined by
+the Forces in the System.  It is possible to create multiple Contexts for a
+single System, and thus have multiple simulations of that System in progress at
+the same time.
+
+:cpp:class:`Integrator <OpenMM::Integrator>`\ : This implements an algorithm for advancing the simulation
+through time.  It is an abstract class; subclasses implement specific
+algorithms.  Examples of Integrator subclasses include :cpp:class:`LangevinIntegrator <OpenMM::LangevinIntegrator>`,
+:cpp:class:`VerletIntegrator <OpenMM::VerletIntegrator>`, and :cpp:class:`BrownianIntegrator <OpenMM::BrownianIntegrator>`.
+
+:cpp:class:`State <OpenMM::State>`\ : A State stores a snapshot of the simulation at a particular point
+in time.  It is created by calling a method on a Context. This is the only way to query the
+values of state variables, such as particle positions and velocities; Context
+does not provide methods for accessing them directly.

docs-source/api-c++/library.rst.jinja2

+.. _core-objects:
+Core Objects
+~~~~~~~~~~~~
+
+.. autodoxysummary::
+    :toctree: generated/
+
+{% for obj in core %}
+    ~{{obj}}
+{% endfor %}
+
+|
+|
+
+.. _forces:
+Forces
+~~~~~~
+
+.. autodoxysummary::
+    :toctree: generated/
+
+{% for force in forces %}
+    ~{{force}}
+{% endfor %}
+
+|
+|
+
+.. _integrators:
+Integrators
+~~~~~~~~~~~
+
+These integrators implement an algorithm for advancing the simulation
+through time.
+
+.. autodoxysummary::
+    :toctree: generated/
+
+{% for integrator in integrators %}
+    ~{{integrator}}
+{% endfor %}
+
+|
+|
+
+.. _extras:
+Extras
+~~~~~~
+
+.. autodoxysummary::
+    :toctree: generated/
+
+{% for extra in extras %}
+    ~{{extra}}
+{% endfor %}

docs-source/api-c++/render.py

+from __future__ import print_function
+import os
+import sys
+from functools import reduce
+from os.path import basename, dirname, join, splitext
+from glob import glob
+
+import jinja2
+import lxml.etree as ET
+
+
+def load_doxygen_xml(doxygen_xml):
+    files = [os.path.join(doxygen_xml, f)
+             for f in os.listdir(doxygen_xml)
+             if f.lower().endswith('.xml') and not f.startswith('._')]
+    if len(files) == 0:
+        raise err
+
+    document = ET.ElementTree(ET.Element('root')).getroot()
+    for file in files:
+        root = ET.parse(file).getroot()
+        for node in root:
+            document.append(node)
+    return document
+
+
+def subclasses(root, parent):
+    parent_el = root.xpath('.//compounddef/compoundname[text()="%s"]/..' % parent)
+    if len(parent_el) == 1:
+        parent_id = parent_el[0].get('id')
+    else:
+        raise ValueError("Can't find %s" % parent)
+
+    xp_query = ('.//compounddef/basecompoundref[@refid="%s"]'
+                '/../compoundname') % parent_id
+    return [parent] + [n.text.strip() for n in root.xpath(xp_query)]
+
+
+def allclasses(root):
+    xp_query = './/compounddef[@kind="class" and @prot="public"]/compoundname'
+    return [e.text for e in root.xpath(xp_query)]
+
+
+def template_data(root):
+    data = {
+        'core': ('OpenMM::System', 'OpenMM::Context', 'OpenMM::State', 'OpenMM::Platform'),
+        'forces': sorted(subclasses(root, 'OpenMM::Force')),
+        'integrators': sorted(subclasses(root, 'OpenMM::Integrator')),
+
+    }
+    data['extras'] = sorted(set(allclasses(root)) -
+                            reduce(set.union, map(set, data.values())))
+    return data
+
+
+def main():
+    if len(sys.argv) == 1:
+        print('usage: %s <doxygen_xml_path>' % sys.argv[0], file=sys.stderr)
+        exit(1)
+    doxygen_xml_path = sys.argv[1]
+
+    root = load_doxygen_xml(doxygen_xml_path)
+    data = template_data(root)
+
+    here = dirname(__file__)
+    templateLoader = jinja2.FileSystemLoader(here)
+    templateEnv = jinja2.Environment(loader=templateLoader)
+
+    for template_fn in map(basename, glob(join(here, '*.jinja2'))):
+        output_fn = splitext(template_fn)[0]
+        print('Rendering %s to %s...' % (template_fn, output_fn))
+
+        template = templateEnv.get_template(template_fn)
+        output_text = template.render(data)
+        with open(output_fn, 'w') as f:
+            f.write(output_text)
+
+
+if __name__ == '__main__':
+    main()

docs-source/api-python/CMakeLists.txt

+set(STAGING_OUTPUT_FILES "") # Will contain all required package files
+file(GLOB STAGING_INPUT_FILES RELATIVE "${CMAKE_CURRENT_SOURCE_DIR}"
+    "app.rst.jinja2"
+    "library.rst.jinja2"
+    "index.rst"
+    "render.py"
+    "conf.py"
+    "process-docstring.py"
+    "_static/logo.png"
+    "_templates/class.rst"
+)
+
+foreach(INIT_FILE ${STAGING_INPUT_FILES})
+    set(infile "${CMAKE_CURRENT_SOURCE_DIR}/${INIT_FILE}")
+    set(outfile "${CMAKE_CURRENT_BINARY_DIR}/${INIT_FILE}")
+    add_custom_command(
+        OUTPUT "${outfile}"
+        COMMAND "${CMAKE_COMMAND}" -E copy_if_different "${infile}" "${outfile}"
+        DEPENDS "${infile}"
+        COMMENT "CMake-copying file ${infile} to ${outfile}")
+    set(STAGING_OUTPUT_FILES ${STAGING_OUTPUT_FILES} "${outfile}")
+endforeach(INIT_FILE ${STAGING_INPUT_FILES})
+
+
+add_custom_command(
+    OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/app.rst"
+           "${CMAKE_CURRENT_BINARY_DIR}/library.rst"
+    COMMAND "${PYTHON_EXECUTABLE}" "${CMAKE_CURRENT_BINARY_DIR}/render.py"
+    DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/app.rst.jinja2"
+            "${CMAKE_CURRENT_BINARY_DIR}/library.rst.jinja2"
+            "${CMAKE_CURRENT_BINARY_DIR}/render.py"
+)
+
+add_custom_command(
+    OUTPUT "${CMAKE_BINARY_DIR}/api-python/index.html"
+    COMMAND "${PYTHON_EXECUTABLE}" -m sphinx . "${CMAKE_BINARY_DIR}/api-python"
+    WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
+    DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/conf.py"
+            "${CMAKE_CURRENT_BINARY_DIR}/process-docstring.py"
+            "${CMAKE_CURRENT_BINARY_DIR}/app.rst"
+            "${CMAKE_CURRENT_BINARY_DIR}/library.rst"
+            "${CMAKE_CURRENT_BINARY_DIR}/index.rst"
+            "${CMAKE_CURRENT_BINARY_DIR}/_static/logo.png"
+            "${CMAKE_CURRENT_BINARY_DIR}/_templates/class.rst"
+            # PythonInstall
+)
+file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/api-python/)
+add_custom_target(PythonApiDocs DEPENDS ${CMAKE_BINARY_DIR}/api-python/index.html)
+INSTALL(DIRECTORY "${CMAKE_BINARY_DIR}/api-python/"
+        DESTINATION "docs/api-python/")
+INSTALL(FILES "${CMAKE_CURRENT_SOURCE_DIR}/../Python API Reference.html"
+        DESTINATION "docs/")

docs-source/api-python/_templates/class.rst

+{{ objname }}
+{{ underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: Methods
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Attributes
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs-source/api-python/app.rst.jinja2

+.. _app :
+
+Application Layer
+=================
+
+Loaders and Setup
+~~~~~~~~~~~~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+
+{% for fileclass in fileclasses %}
+    ~{{ fileclass }}
+{% endfor %}
+
+
+Representation and Manipulation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+
+    ~simtk.openmm.app.topology.Topology
+    ~simtk.openmm.app.modeller.Modeller
+
+Simulation
+~~~~~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+
+    ~simtk.openmm.app.forcefield.ForceField
+    ~simtk.openmm.app.simulation.Simulation
+
+
+Reporting Output
+~~~~~~~~~~~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+
+{% for reporter in reporters %}
+    ~{{ reporter }}
+{% endfor %}
+
+
+Extras
+~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+
+    {% for extra in app_extras %}
+    ~{{ extra }}
+    {% endfor %}

docs-source/api-python/conf.py

+# -*- coding: utf-8 -*-
+
+import sys
+import os
+import simtk.openmm.version
+
+extensions = ['sphinx.ext.mathjax', 'sphinx.ext.ifconfig', 'sphinx.ext.autosummary',
+              'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'process-docstring',
+              'sphinxcontrib.lunrsearch']
+
+autosummary_generate = True
+autodoc_default_flags = ['members', 'inherited-members']
+autodoc_member_order = 'bysource'
+
+source_suffix = '.rst'
+master_doc = 'index'
+
+project = u'OpenMM'
+copyright = u'2015, Stanford University and the Authors'
+
+version = simtk.openmm.version.short_version
+release = simtk.openmm.version.full_version
+
+exclude_patterns = ['_build', '_templates']
+html_static_path = ['_static']
+templates_path = ['_templates']
+
+pygments_style = 'sphinx'
+
+html_theme = "alabaster"
+html_theme_options = {
+    'description': "High performance molecular simulation on GPUs",
+    'github_button': False,
+    # 'github_user': 'pandegroup',
+    # 'github_repo': 'openmm',
+    'logo_name': False,
+    'logo': 'logo.png',
+}
+html_sidebars = {
+    '**': [
+        'about.html',
+        'searchbox.html',
+        'navigation.html',
+    ]
+}
+
+# Napoleon settings
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True

docs-source/api-python/index.rst

+.. currentmodule:: simtk.openmm.openmm
+
+OpenMM Python API
+=================
+
+The Python API provides information about the classes and methods available in OpenMM for Python developers.
+
+OpenMM consists of two parts. First, there is a set of :ref:`libraries <library>` for performing many types of computations needed for molecular simulations: force evaluation, numerical integration, energy minimization, etc.
+
+Second, there is an :ref:`application layer <app>`, a set of Python libraries providing a 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.
+
+See the user guide for more details.
+
+
+.. toctree::
+   :maxdepth: 2
+
+   app
+   library

docs-source/api-python/library.rst.jinja2

+.. _library :
+
+Library Layer
+=============
+
+
+Core Objects
+~~~~~~~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+    :nosignatures:
+
+    ~simtk.openmm.openmm.System
+    ~simtk.openmm.openmm.Context
+    ~simtk.openmm.openmm.Platform
+    ~simtk.openmm.openmm.State
+
+
+Forces
+~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+    :nosignatures:
+
+    {% for force in forces %}
+    ~{{ force }}
+    {% endfor %}
+
+
+Integrators
+~~~~~~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+    :nosignatures:
+
+    {% for integrator in integrators %}
+    ~{{ integrator }}
+    {% endfor %}
+
+Extras
+~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+    :nosignatures:
+
+    {% for extra in library_extras %}
+    ~{{ extra }}
+    {% endfor %}

docs-source/api-python/process-docstring.py

+import re
+
+def process_docstring(app, what, name, obj, options, lines):
+    """This hook edits the docstrings to replace "<tt><pre>" html tags
+    with sphinx directives.
+    """
+    def repl(m):
+        s = m.group(1)
+        if not s.startswith(linesep):
+            s = linesep + s
+        newline = '.. code-block:: c++' + linesep
+        return newline + '    ' + s.replace(linesep, linesep + '    ')
+
+    if name == 'simtk.openmm.openmm.CustomTorsionForce':
+         print(lines)
+
+    linesep = '|LINEBREAK|'
+    joined = linesep.join(lines)
+
+    joined = re.sub(r'<tt><pre>((|LINEBREAK|)?.*?)</pre></tt>', repl, joined)
+    joined = re.sub(r'<tt>(.*?)</tt>', repl, joined)
+    lines[:] = [(l if not l.isspace() else '') for l in joined.split(linesep)]
+
+
+def setup(app):
+    app.connect('autodoc-process-docstring', process_docstring)
+
+
+def test():
+    lines    = ['Hello World', '<tt><pre>', 'contents', '</pre></tt>', '', '<tt>contents2</tt>']
+    linesRef = ['Hello World', '.. code-block:: c++', '', '    contents', '', '', '.. code-block:: c++', '', '    contents2']
+    process_docstring(None, None, None, None, None, lines)
+    assert lines == linesRef
+
+if __name__ == '__main__':
+    test()