From 8503794b603ce21189fba8cd1b84318fce2b78e3 Mon Sep 17 00:00:00 2001 From: Jinzhe Zeng Date: Fri, 20 Aug 2021 01:56:35 -0400 Subject: [PATCH 1/3] generate Python API document automatically --- .gitignore | 3 +- doc/conf.py | 17 +++++- doc/development/api.rst | 123 ---------------------------------------- doc/index.rst | 3 +- setup.py | 2 +- 5 files changed, 19 insertions(+), 129 deletions(-) delete mode 100644 doc/development/api.rst diff --git a/.gitignore b/.gitignore index dbcf687197..e9b29e2382 100644 --- a/.gitignore +++ b/.gitignore @@ -27,7 +27,8 @@ venv* _build _templates API_CC +doc/api_py/ dp/ build_lammps/ build_tests/ -build_cc_tests \ No newline at end of file +build_cc_tests diff --git a/doc/conf.py b/doc/conf.py index 0dfac83f24..985676517f 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -130,10 +130,19 @@ def generate_doxygen_xml(app): else: subprocess.call("doxygen Doxyfile", shell=True) +def run_apidoc(_): + from sphinx.ext.apidoc import main + import sys + sys.path.append(os.path.join(os.path.dirname(__file__), '..')) + cur_dir = os.path.abspath(os.path.dirname(__file__)) + module = os.path.join(cur_dir,"..","deepmd") + main(['-M', '--tocfile', 'api_py', '-H', 'Python API', '-o', os.path.join(cur_dir, "api_py"), module, '--force']) + def setup(app): # Add hook for building doxygen xml when needed app.connect("builder-inited", generate_doxygen_xml) + app.connect('builder-inited', run_apidoc) # -- General configuration --------------------------------------------------- @@ -158,6 +167,7 @@ def setup(app): 'sphinx.ext.autosummary', 'sphinx.ext.viewcode', 'sphinx.ext.intersphinx', + 'numpydoc', 'breathe', 'exhale' ] @@ -184,10 +194,10 @@ def setup(app): } # Tell sphinx what the primary language being documented is. -primary_domain = 'cpp' +#primary_domain = 'cpp' # Tell sphinx what the pygments highlight language should be. -highlight_language = 'cpp' +#highlight_language = 'cpp' # myst_heading_anchors = 4 @@ -206,7 +216,8 @@ def setup(app): "tensorflow": ( "https://www.tensorflow.org/api_docs/python", "https://github.com/mr-ubik/tensorflow-intersphinx/raw/master/tf2_py_objects.inv", - ), + ), + "ase": ("https://wiki.fysik.dtu.dk/ase/", "objects.inv"), } # -- Options for HTML output ------------------------------------------------- diff --git a/doc/development/api.rst b/doc/development/api.rst deleted file mode 100644 index eda136f00e..0000000000 --- a/doc/development/api.rst +++ /dev/null @@ -1,123 +0,0 @@ -Python API -========== - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - -.. automodule:: deepmd.utils.data - :members: - :undoc-members: - -.. automodule:: deepmd.infer.data_modifier - :members: - :undoc-members: - -.. automodule:: deepmd.utils.data_system - :members: - :undoc-members: - -.. automodule:: deepmd.infer.deep_eval - :members: - :undoc-members: - -.. automodule:: deepmd.infer.deep_polar - :members: - :undoc-members: - -.. automodule:: deepmd.infer.deep_pot - :members: - :undoc-members: - -.. automodule:: deepmd.infer.deep_wfc - :members: - :undoc-members: - -.. automodule:: deepmd.descriptor.loc_frame - :members: - :undoc-members: - -.. automodule:: deepmd.descriptor.se_a - :members: - :undoc-members: - -.. automodule:: deepmd.descriptor.se_r - :members: - :undoc-members: - -.. automodule:: deepmd.descriptor.se_ar - :members: - :undoc-members: - -.. automodule:: deepmd.descriptor.se_a_ebd - :members: - :undoc-members: - -.. automodule:: deepmd.descriptor.se_t - :members: - :undoc-members: - -.. automodule:: deepmd.descriptor.se_a_ef - :members: - :undoc-members: - -.. automodule:: deepmd.descriptor.hybrid - :members: - :undoc-members: - -.. automodule:: deepmd.infer.ewald_recp - :members: - :undoc-members: - -.. automodule:: deepmd.fit.ener - :members: - :undoc-members: - -.. automodule:: deepmd.fit.dipole - :members: - :undoc-members: - -.. automodule:: deepmd.fit.polar - :members: - :undoc-members: - -.. automodule:: deepmd.fit.wfc - :members: - :undoc-members: - -.. automodule:: deepmd.utils.network - :members: - :undoc-members: - -.. automodule:: deepmd.utils.learning_rate - :members: - :undoc-members: - -.. automodule:: deepmd.cluster.local - :members: - :undoc-members: - -.. automodule:: deepmd.cluster.slurm - :members: - :undoc-members: - -.. automodule:: deepmd.loss.ener - :members: - :undoc-members: - -.. automodule:: deepmd.loss.tensor - :members: - :undoc-members: - -.. automodule:: deepmd.model.ener - :members: - :undoc-members: - -.. automodule:: deepmd.model.tensor - :members: - :undoc-members: - -.. automodule:: deepmd.train.trainer - :members: - :undoc-members: - diff --git a/doc/index.rst b/doc/index.rst index 7cd8968f01..2b6cf74fbf 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -39,11 +39,12 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r .. _developer-guide: .. toctree:: - :maxdepth: 3 + :maxdepth: 5 :caption: Developer Guide :glob: development/* + api_py/api_py API_CC/api_cc diff --git a/setup.py b/setup.py index e48f9a3f3d..0c7aba7657 100644 --- a/setup.py +++ b/setup.py @@ -125,7 +125,7 @@ cmake_minimum_required_version="3.0", extras_require={ "test": ["dpdata>=0.1.9", "ase", "pytest", "pytest-cov", "pytest-sugar"], - "docs": ["sphinx<4.1.0", "recommonmark", "sphinx_rtd_theme", "sphinx_markdown_tables", "myst-parser", "breathe", "exhale"], + "docs": ["sphinx>=3.1.1,<4.1.0", "recommonmark", "sphinx_rtd_theme", "sphinx_markdown_tables", "myst-parser", "breathe", "exhale", "numpydoc"], **extras_require, }, entry_points={"console_scripts": ["dp = deepmd.entrypoints.main:main"]}, From 9779aadf8bff5917feb73a808fb08076abb8e7b0 Mon Sep 17 00:00:00 2001 From: Jinzhe Zeng Date: Fri, 20 Aug 2021 02:06:31 -0400 Subject: [PATCH 2/3] add `ase` to generate `deepmd.calculator` --- setup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.py b/setup.py index 0c7aba7657..35ef146879 100644 --- a/setup.py +++ b/setup.py @@ -125,7 +125,7 @@ cmake_minimum_required_version="3.0", extras_require={ "test": ["dpdata>=0.1.9", "ase", "pytest", "pytest-cov", "pytest-sugar"], - "docs": ["sphinx>=3.1.1,<4.1.0", "recommonmark", "sphinx_rtd_theme", "sphinx_markdown_tables", "myst-parser", "breathe", "exhale", "numpydoc"], + "docs": ["sphinx>=3.1.1,<4.1.0", "recommonmark", "sphinx_rtd_theme", "sphinx_markdown_tables", "myst-parser", "breathe", "exhale", "numpydoc", "ase"], **extras_require, }, entry_points={"console_scripts": ["dp = deepmd.entrypoints.main:main"]}, From 6818c1ecd7d4818fb9a426df2b4922e00056910c Mon Sep 17 00:00:00 2001 From: Jinzhe Zeng Date: Fri, 20 Aug 2021 02:51:09 -0400 Subject: [PATCH 3/3] fix `ase` intersphinx_mapping --- doc/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 985676517f..f7515cb7b3 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -217,7 +217,7 @@ def setup(app): "https://www.tensorflow.org/api_docs/python", "https://github.com/mr-ubik/tensorflow-intersphinx/raw/master/tf2_py_objects.inv", ), - "ase": ("https://wiki.fysik.dtu.dk/ase/", "objects.inv"), + "ase": ("https://wiki.fysik.dtu.dk/ase/", None), } # -- Options for HTML output -------------------------------------------------