Sphinx C++ documentation

docs-source/CMakeLists.txt

@@ -6,43 +6,8 @@ find_package(Doxygen QUIET)
 mark_as_advanced(CLEAR DOXYGEN_EXECUTABLE)
 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"
-        ${OPENMM_INCLUDES}
-        ${OLLA_INCLUDES}
-    )
-    set(OPENMM_GENERATE_API_DOCS OFF CACHE BOOL "Whether to create API documentation")
     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

docs-source/api-c++/.gitignore

+_build
+generated

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}"
+    "index.rst"
+    "core.rst.jinja2"
+    "integrators.rst.jinja2"
+    "forces.rst.jinja2"
+    "extras.rst.jinja2"
+    "render.py"
+    "_static/logo.png"
+)
+
+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})
+
+
+set(DOXYGEN_XML_DIRECTORY "${CMAKE_BINARY_DIR}/wrappers/python/src/swig_doxygen/doxygen/xml/")
+configure_file("${CMAKE_CURRENT_SOURCE_DIR}/conf.py" "${CMAKE_CURRENT_BINARY_DIR}/conf.py")
+
+
+add_custom_command(
+    OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/core.rst"
+           "${CMAKE_CURRENT_BINARY_DIR}/integrators.rst"
+           "${CMAKE_CURRENT_BINARY_DIR}/forces.rst"
+           "${CMAKE_CURRENT_BINARY_DIR}/extras.rst"
+    COMMAND "${PYTHON_EXECUTABLE}" "${CMAKE_CURRENT_BINARY_DIR}/render.py"
+            "${CMAKE_BINARY_DIR}/wrappers/python/src/swig_doxygen/doxygen/xml/"
+    DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/render.py"
+            "${CMAKE_CURRENT_BINARY_DIR}/core.rst.jinja2"
+            "${CMAKE_CURRENT_BINARY_DIR}/integrators.rst.jinja2"
+            "${CMAKE_CURRENT_BINARY_DIR}/forces.rst.jinja2"
+            "${CMAKE_CURRENT_BINARY_DIR}/extras.rst.jinja2"
+            "${CMAKE_BINARY_DIR}/wrappers/python/src/swig_doxygen/doxygen/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}/core.rst"
+            "${CMAKE_CURRENT_BINARY_DIR}/forces.rst"
+            "${CMAKE_CURRENT_BINARY_DIR}/extras.rst"
+            "${CMAKE_CURRENT_BINARY_DIR}/integrators.rst"
+            "${CMAKE_CURRENT_BINARY_DIR}/index.rst"
+            "${CMAKE_CURRENT_BINARY_DIR}/_static/logo.png"
+)
+
+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_DIRECTORY@"

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

+Core Objects
+~~~~~~~~~~~~
+
+.. autodoxysummary::
+    :toctree: generated/
+
+{% for obj in core %}
+    ~{{obj}}
+{% endfor %}

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

+Extras
+~~~~~~
+
+.. autodoxysummary::
+    :toctree: generated/
+
+{% for extra in extras %}
+    ~{{extra}}
+{% endfor %}

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

+Forces
+~~~~~~
+
+.. autodoxysummary::
+    :toctree: generated/
+
+{% for force in forces %}
+    ~{{force}}
+{% endfor %}

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.
+
+.. toctree::
+   :maxdepth: 1
+
+   core
+   forces
+   integrators
+   extras

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

+Integrators
+~~~~~~~~~~~
+
+.. autodoxysummary::
+    :toctree: generated/
+
+{% for integrator in integrators %}
+    ~{{integrator}}
+{% endfor %}

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

+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):
+    xp_query = ('.//compounddef/basecompoundref[text()="%s"]'
+                '/../compoundname') % parent
+    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::State'),
+        '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()