doc: dpgen run machine parameters (#710)

* doc: dpgen run machine parameters

* unpin sphinx

Fix sphinx-doc/sphinx#10291 (comment)

Author: njzjz

doc/conf.py

@@ -11,6 +11,7 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
+import sys
 import subprocess
 # import sys
 import recommonmark
@@ -79,3 +80,10 @@
 autodoc_default_flags = ['members']
 autosummary_generate = True
 master_doc = 'index'
+
+
+def generate_arginfo(app):
+    subprocess.check_output((sys.executable, "gen_arginfo.py"), universal_newlines=True)
+
+def setup(app):
+    app.connect('builder-inited', generate_arginfo)

doc/gen_arginfo.py

@@ -0,0 +1,5 @@
+from dpgen.generator.arginfo import run_mdata_arginfo
+
+run_mdata_doc = run_mdata_arginfo().gen_doc()
+with open('run-mdata-auto.rst', 'w') as f:
+    f.write(run_mdata_doc)

doc/index.rst

@@ -2,6 +2,14 @@
 DPGEN's documentation
 ==========================
 
+.. _parameters::
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Parameters
+
+   run-mdata.rst
+
 .. _tutorial:
 
 .. toctree::

doc/requirements.txt

@@ -1,6 +1,7 @@
-sphinx==3.2.1
-recommonmark==0.7.1
-sphinx_rtd_theme==0.5.2
-sphinx_markdown_tables==0.0.15
-myst-parser==0.13.7
+sphinx>=4.0.2
+recommonmark
+sphinx_rtd_theme
+sphinx_markdown_tables
+myst-parser
 deepmodeling_sphinx
+.

doc/run-mdata.rst

@@ -0,0 +1,4 @@
+dpgen run machine parameters
+============================
+
+.. include:: run-mdata-auto.rst

dpgen/dispatcher/Dispatcher.py

@@ -1,5 +1,6 @@
 from distutils.version import LooseVersion
 import os,sys,time,random,json,glob
+from typing import List
 from dpdispatcher import Task, Submission, Resources, Machine
 from dpgen.dispatcher.LocalContext import LocalSession
 from dpgen.dispatcher.LocalContext import LocalContext
@@ -383,5 +384,25 @@ def make_submission(mdata_machine, mdata_resources, commands, work_path, run_tas
     return submission
 
 
+def mdata_arginfo() -> List[Argument]:
+    """This method generates arginfo for a single mdata.
 
-
+    A submission requires the following keys: command, machine,
+    and resources.
+    
+    Returns
+    -------
+    list[Argument]
+        arginfo
+    """
+    doc_command = "Command of a program."
+    doc_mdata = "Machine and resources parameters"
+    command_arginfo = Argument("command", str, optional=False, doc=doc_command)
+    machine_arginfo = Machine.arginfo()
+    machine_arginfo.name = "machine"
+    resources_arginfo = Resources.arginfo()
+    resources_arginfo.name = "resources"
+
+    return [
+        command_arginfo, machine_arginfo, resources_arginfo,
+    ]

dpgen/generator/arginfo.py

@@ -0,0 +1,25 @@
+from dargs import Argument
+
+from dpgen.dispatcher.Dispatcher import mdata_arginfo
+
+def run_mdata_arginfo() -> Argument:
+    """Generate arginfo for dpgen run mdata.
+    
+    Returns
+    -------
+    Argument
+        arginfo
+    """
+    
+    doc_api_version = "Please set to 1.0"
+    doc_run_mdata = "machine.json file"
+    arg_api_version = Argument("api_version", str, optional=False, doc=doc_api_version)
+
+    sub_fields = [arg_api_version]
+    doc_mdata = "Parameters of command, machine, and resources for %s"
+    for task in ("train", "model_devi", "fp"):
+        sub_fields.append(Argument(
+            task, dict, optional=False, sub_fields=mdata_arginfo(),
+            doc=doc_mdata % task,
+        ))
+    return Argument("run_mdata", dict, sub_fields=sub_fields, doc=doc_run_mdata)