From 004cdaa6d743f84e4db0a14bd1468426b4ee0ef0 Mon Sep 17 00:00:00 2001
From: Jinzhe Zeng <jinzhe.zeng@rutgers.edu>
Date: Fri, 10 Jun 2022 02:20:41 -0400
Subject: [PATCH 1/2] add auto cli docs

This commit adds the automatic documentation for command line interface, generated by a sphinx extension.
---
 deepmd/entrypoints/main.py | 30 +++++++++++++++++++++++-------
 doc/conf.py                |  1 +
 doc/inference/cli.rst      |  7 +++++++
 doc/inference/index.rst    |  1 +
 setup.py                   |  2 +-
 5 files changed, 33 insertions(+), 8 deletions(-)
 create mode 100644 doc/inference/cli.rst

diff --git a/deepmd/entrypoints/main.py b/deepmd/entrypoints/main.py
index e35cc1086f..949797ea8b 100644
--- a/deepmd/entrypoints/main.py
+++ b/deepmd/entrypoints/main.py
@@ -20,7 +20,7 @@
 )
 from deepmd.loggers import set_log_handles
 
-__all__ = ["main", "parse_args", "get_ll"]
+__all__ = ["main", "parse_args", "get_ll", "main_parser"]
 
 
 def get_ll(log_level: str) -> int:
@@ -44,14 +44,13 @@ def get_ll(log_level: str) -> int:
     return int_level
 
 
-def parse_args(args: Optional[List[str]] = None):
+def main_parser() -> argparse.ArgumentParser:
     """DeePMD-Kit commandline options argument parser.
 
-    Parameters
-    ----------
-    args: List[str]
-        list of command line arguments, main purpose is testing default option None
-        takes arguments from sys.argv
+    Returns
+    -------
+    argparse.ArgumentParser
+        main parser of DeePMD-kit
     """
     parser = argparse.ArgumentParser(
         description="DeePMD-kit: A deep learning package for many-body potential energy"
@@ -440,7 +439,24 @@ def parse_args(args: Optional[List[str]] = None):
         
     # --version
     parser.add_argument('--version', action='version', version='DeePMD-kit v%s' % __version__)
+    return parser
+
+
+def parse_args(args: Optional[List[str]] = None) -> argparse.Namespace:
+    """Parse arguments and convert argument strings to objects.
 
+    Parameters
+    ----------
+    args: List[str]
+        list of command line arguments, main purpose is testing default option None
+        takes arguments from sys.argv
+
+    Returns
+    -------
+    argparse.Namespace
+        the populated namespace
+    """
+    parser = main_parser()
     parsed_args = parser.parse_args(args=args)
     if parsed_args.command is None:
         parser.print_help()
diff --git a/doc/conf.py b/doc/conf.py
index 29a8ecd4f0..a2ccf05c63 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -175,6 +175,7 @@ def setup(app):
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
     'sphinx.ext.intersphinx',
+    'sphinxarg.ext',
     'numpydoc',
     'breathe',
     'exhale'
diff --git a/doc/inference/cli.rst b/doc/inference/cli.rst
new file mode 100644
index 0000000000..4c52a9ede8
--- /dev/null
+++ b/doc/inference/cli.rst
@@ -0,0 +1,7 @@
+Command line interface
+======================
+
+.. argparse::
+   :module: deepmd.entrypoints.main
+   :func: main_parser
+   :prog: dp
diff --git a/doc/inference/index.rst b/doc/inference/index.rst
index 5b591e309c..14e12832ee 100644
--- a/doc/inference/index.rst
+++ b/doc/inference/index.rst
@@ -8,3 +8,4 @@ Note that the model for inference is required to be compatible with the DeePMD-k
 
    python
    cxx
+   cli
diff --git a/setup.py b/setup.py
index 2623f0f149..77520c9fcf 100644
--- a/setup.py
+++ b/setup.py
@@ -127,7 +127,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", "recommonmark", "sphinx_rtd_theme>=1.0.0rc1", "sphinx_markdown_tables", "myst-parser", "breathe", "exhale", "numpydoc", "ase", "deepmodeling-sphinx"],
+        "docs": ["sphinx>=3.1.1", "recommonmark", "sphinx_rtd_theme>=1.0.0rc1", "sphinx_markdown_tables", "myst-parser", "breathe", "exhale", "numpydoc", "ase", "deepmodeling-sphinx", "sphinx-argparse"],
         **extras_require,
     },
     entry_points={"console_scripts": ["dp = deepmd.entrypoints.main:main"]},

From 464a3cb2a4ba126ab84b5e132bdcebaf5e9112c9 Mon Sep 17 00:00:00 2001
From: Jinzhe Zeng <jinzhe.zeng@rutgers.edu>
Date: Sat, 11 Jun 2022 01:13:30 -0400
Subject: [PATCH 2/2] move cli out of inference

it should be not related to inference..
---
 doc/{inference => }/cli.rst | 0
 doc/index.rst               | 1 +
 doc/inference/index.rst     | 1 -
 3 files changed, 1 insertion(+), 1 deletion(-)
 rename doc/{inference => }/cli.rst (100%)

diff --git a/doc/inference/cli.rst b/doc/cli.rst
similarity index 100%
rename from doc/inference/cli.rst
rename to doc/cli.rst
diff --git a/doc/index.rst b/doc/index.rst
index 2b6cf74fbf..5ba11a764a 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -33,6 +33,7 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r
    freeze/index
    test/index
    inference/index
+   cli
    third-party/index
    troubleshooting/index
 
diff --git a/doc/inference/index.rst b/doc/inference/index.rst
index 14e12832ee..5b591e309c 100644
--- a/doc/inference/index.rst
+++ b/doc/inference/index.rst
@@ -8,4 +8,3 @@ Note that the model for inference is required to be compatible with the DeePMD-k
 
    python
    cxx
-   cli