Optimized mkindex function in doc/conf.py and added two files in troubleshooting.

doc/conf.py

@@ -15,47 +15,37 @@
 import recommonmark
 from recommonmark.transform import AutoStructify
 
-def mkindex_troubleshooting():
-    oldfindex = open("troubleshooting/index.md", "r")
-    _oldlist = oldfindex.readlines()
-    oldlist = _oldlist[4:]
+def mkindex(dirname):
+    dirname = dirname + "/"
+    oldfindex = open(dirname + "index.md", "r")
+    oldlist = oldfindex.readlines()
     oldfindex.close()
-
-    newfindex = open("troubleshooting/index.md", "a")
-    for root, dirs, files in os.walk("./troubleshooting/", topdown=False):
-        for name in files:
-            if (name == "index.md"):
-                continue
-            if (name[-3:] == ".md"):
-                longname = "- ["+name[:-3]+"]("+name+")\n"
-                if (longname not in oldlist):
-                    newfindex.write(longname)
-
-    newfindex.close()
 
-def mkindex_development():
-    oldfindex = open("development/index.md", "r")
-    _oldlist = oldfindex.readlines()
-    oldlist = _oldlist[2:]
-    oldfindex.close()
+    oldnames = []
+    for entry in oldlist:
+        _name = entry[entry.find("(")+1 : entry.find(")")]
+        oldnames.append(_name)
 
-    newfindex = open("development/index.md", "a")
-    for root, dirs, files in os.walk("./development/", topdown=False):
-        for name in files:
-            if (name == "index.md"):
-                continue
-            if (name[-3:] == ".md"):
-                longname = "- ["+name[:-3]+"]("+name+")\n"
-                if (longname not in oldlist):
-                    newfindex.write(longname)
-            else:
-                if (name[-4:] == ".rst"):
-                    longname = "- ["+name[:-4]+"]("+name+")\n"
-                    if (longname not in oldlist):
-                        newfindex.write(longname)
+    newfindex = open(dirname + "index.md", "a")
+    for root, dirs, files in os.walk(dirname, topdown=False):
+        newnames = [name for name in files if name != "index.md" and name not in oldnames]
+        for name in newnames:
+            f = open(dirname + name, "r")
+            _lines = f.readlines()
+            for _headline in _lines:
+                _headline = _headline.strip("#")
+                headline = _headline.strip()
+                if (len(headline) == 0 or headline[0] == "." or headline[0] == "="):
+                    continue
+                else:
+                    break
+            longname = "- ["+headline+"]"+"("+name+")\n"
+            newfindex.write(longname)
+
 
     newfindex.close()
 
+
 # -- Project information -----------------------------------------------------
 
 project = 'DeePMD-kit'
@@ -76,8 +66,8 @@ def mkindex_development():
 #     'sphinx.ext.autosummary'
 # ]
 
-mkindex_troubleshooting()
-mkindex_development()
+mkindex("troubleshooting")
+mkindex("development")
 
 extensions = [
     "sphinx_rtd_theme",

doc/development/index.md

@@ -1,4 +1,4 @@
 # Developer Guide
 
-- [coding-conventions](coding-conventions.rst)
-- [api](api.rst)
+- [API](api.rst)
+- [Coding Conventions](coding-conventions.rst)

doc/troubleshooting/index.md

@@ -2,6 +2,9 @@
 In consequence of various differences of computers or systems, problems may occur. Some common circumstances are listed as follows. 
 If other unexpected problems occur, you're welcome to contact us for help.
 
-- [installation](installation.md)
-- [md-version-compatibility](md-version-compatibility.md)
-- [model-compatability](model-compatability.md)
+
+- [Installation](installation.md)
+- [The temperature undulates violently during early stages of MD](md-energy-undulation.md)
+- [MD: cannot run LAMMPS after installing a new version of DeePMD-kit](md-version-compatibility.md)
+- [Model compatability](model-compatability.md)
+- [Do we need to set rcut < half boxsize ?](rcut.md)

doc/troubleshooting/md-energy-undulation.md

@@ -0,0 +1,5 @@
+# The temperature undulates violently during early stages of MD
+
+This is probably because your structure is too far from the equlibrium configuration.
+
+Although, to make sure the potential model is truly accurate, we recommend to check model deviation.

doc/troubleshooting/rcut.md

@@ -0,0 +1,7 @@
+# Do we need to set rcut < half boxsize ?
+
+When seeking the neighbors of atom i under periodic boundary condition, deepmd-kit considers all j atoms within cutoff R<sub>cut</sub> from atom i in all mirror cells.
+
+So there is no limitation on the setting of R<sub>cut</sub>.
+
+PS: The reason why some softwares require R<sub>cut</sub> < half boxsize is that they only consider the nearest mirrors from the center cell. Deepmd-kit is totally different from them.