Doc api cc (#663)

* Doxyfile cannot be installed from pip, therefore I precompiled with doxyfile to generated xml/ from C++. And then api_cc.rst can be generated by breathe from xml/.

* Edit conf.py to include doxygen

* Edit conf.py to enable doxygen on readthedocs

* Add specification in conf.py to refine the html layout of api_cc.rst

* Included exhale to make prettier C++ API.

* Update conf.py

* add a function description to see if it works

* it should be put into the header file?

* add documents for DeepPot and DeepTensor

* add documents for some common functions

Co-authored-by: tuoping <[email protected]>
Co-authored-by: Jinzhe Zeng <[email protected]>

Author: 3 people

.gitignore

@@ -26,3 +26,4 @@ venv*
 .vscode/**
 _build
 _templates
+API_CC

doc/Doxyfile

@@ -0,0 +1 @@
+To run the HTML documention build, doxygen have to be installed.

doc/README

@@ -1,5 +1,5 @@
-API
-===
+Python API
+==========
 
 .. toctree::
    :maxdepth: 2

doc/development/api.rst renamed to doc/api.rst

@@ -11,6 +11,7 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
+import subprocess
 # import sys
 import recommonmark
 from recommonmark.transform import AutoStructify
@@ -108,6 +109,31 @@ def classify_index_TS():
 copyright = '2020, Deep Potential'
 author = 'Deep Potential'
 
+def run_doxygen(folder):
+    """Run the doxygen make command in the designated folder"""
+
+    try:
+        retcode = subprocess.call("cd %s; doxygen Doxyfile" % folder, shell=True)
+        if retcode < 0:
+            sys.stderr.write("doxygen terminated by signal %s" % (-retcode))
+    except OSError as e:
+        sys.stderr.write("doxygen execution failed: %s" % e)
+
+
+def generate_doxygen_xml(app):
+    """Run the doxygen make commands if we're on the ReadTheDocs server"""
+
+    read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
+
+    if read_the_docs_build:
+        run_doxygen("./")
+    else:
+        subprocess.call("doxygen Doxyfile", shell=True)
+
+def setup(app):
+
+    # Add hook for building doxygen xml when needed
+    app.connect("builder-inited", generate_doxygen_xml)
 
 # -- General configuration ---------------------------------------------------
 
@@ -129,9 +155,39 @@ def classify_index_TS():
 extensions = [
     "sphinx_rtd_theme",
     'myst_parser',
-    'sphinx.ext.autosummary'
+    'sphinx.ext.autosummary',
+    'breathe',
+    'exhale'
 ]
 
+# breathe_domain_by_extension = {
+#         "h" : "cpp",
+# }
+breathe_projects = {"myproject": "_build/xml/"}
+breathe_default_project = "myproject"
+
+exhale_args = {
+   "containmentFolder":     "./API_CC",
+    "rootFileName":          "api_cc.rst",
+    "rootFileTitle":         "C++ API",
+    "doxygenStripFromPath":  "..",
+    # Suggested optional arguments
+    # "createTreeView":        True,
+    # TIP: if using the sphinx-bootstrap-theme, you need
+    # "treeViewIsBootstrap": True,
+    "exhaleExecutesDoxygen": True,
+    "exhaleDoxygenStdin":    "INPUT = ../source/api_cc/include/",
+    # "unabridgedOrphanKinds": {"namespace"}
+    # "listingExclude": [r"namespace_*"]
+}
+
+# Tell sphinx what the primary language being documented is.
+primary_domain = 'cpp'
+
+# Tell sphinx what the pygments highlight language should be.
+highlight_language = 'cpp'
+
+# 
 myst_heading_anchors = 4
 
 # Add any paths that contain templates here, relative to this directory.

doc/conf.py

@@ -1,4 +1,5 @@
 # Developer Guide
 
-- [API](api.rst)
+- [Python API](../api.rst)
+- [C++ API](../API_CC/api_cc.rst)
 - [Coding Conventions](coding-conventions.rst)

doc/development/index.md

@@ -107,7 +107,7 @@
     cmake_minimum_required_version="3.0",
     extras_require={
         "test": ["dpdata>=0.1.9", "ase", "pytest", "pytest-cov", "pytest-sugar"],
-        "docs": ["sphinx", "recommonmark", "sphinx_rtd_theme", "sphinx_markdown_tables", "myst-parser"],
+        "docs": ["sphinx", "recommonmark", "sphinx_rtd_theme", "sphinx_markdown_tables", "myst-parser", "breathe", "exhale"],
         **extras_require,
     },
     entry_points={"console_scripts": ["dp = deepmd.entrypoints.main:main"]},