Re-structured Doc

CONTRIBUTING.md

@@ -0,0 +1,136 @@
+# DeePMD-kit Contributing Guide
+
+Welcome to [DeePMD-kit](https://github.com/deepmodeling/deepmd-kit)!
+
+## What you can contribute
+
+You can either make a code contribution, help improve our document or offer help to other users. Your help is always appreciated. Come and have fun!
+
+### Code contribution
+You can start from any one of the following items to help improve deepmd-kit
+
+- Smash a bug
+- Implement a feature or add a patch, whatever you think deepmd-kit is missing
+- Browse [issues](https://github.com/deepmodeling/deepmd-kit/issues), find an issue labeled enhancement or bug, and help to solve it.
+
+See [here](#before-you-contribute) for some before-hand heads-up. 
+
+See [here](#how-to-contribute) to learn how to contribute.
+
+### Document improvement
+You can start from any one of the following items to help improve [DeePMD-kit Docs](https://deepmd.readthedocs.io/en/latest/?badge=latest):
+
+- Fix typos or format (punctuation, space, indentation, code block, etc.)
+- Fix or update inappropriate or outdated descriptions
+- Add missing content (sentence, paragraph, or a new document)
+- Translate docs changes from English to Chinese
+
+### Offer help
+You can help other users of deepmd-kit in the following way
+
+- Submit, reply to, and resolve [issues](https://github.com/deepmodeling/deepmd-kit/issues)
+- (Advanced) Review Pull Requests created by others
+
+## Before you contribute
+### Overview of DeePMD-kit
+Currently, we maintain two main branch:
+- master: stable branch with version tag
+- devel :  branch for developers
+
+### Developer guide
+See [here](doc/development/index.md) for coding conventions, API and other needs-to-know of the code.
+
+## How to contribute
+Please perform the following steps to create your Pull Request to this repository. If don't like to use commands, you can also use [GitHub Desktop](https://desktop.github.com/), which is easier to get started. Go to [git documentation](https://git-scm.com/doc) if you want to really master git.
+
+### Step 1: Fork the repository
+
+1. Visit the project: <https://github.com/deepmodeling/deepmd-kit>
+2. Click the **Fork** button on the top right and wait it to finish.
+
+### Step 2: Clone the forked repository to local storage and set configurations
+
+1. Clone your own repo, not the public repo (from deepmodeling) ! And change the branch to devel.
+    ```bash
+    git clone https://github.com/$username/deepmd-kit.git
+    # Replace `$username` with your GitHub ID
+
+    git checkout devel
+    ```
+
+2. Add deepmodeling's repo as your remote repo, we can name it "upstream". And fetch upstream's latest codes to your workstation.
+    ```bash
+    git remote add upstream https://github.com/deepmodeling/deepmd-kit.git
+    # After you add a remote repo, your local repo will be automatically named "origin".
+
+    git fetch upstream
+
+    # If your current codes are behind the latest codes, you should merge latest codes first.
+    # Notice you should merge from "devel"!
+    git merge upstream/devel
+    ```
+
+3. Modify your codes and design unit tests.
+
+4. Commit your changes
+    ```bash
+    git status # Checks the local status
+    git add <file> ... # Adds the file(s) you want to commit. If you want to commit all changes, you can directly use `git add.`
+    git commit -m "commit-message: update the xx"
+    ```
+
+5. Push the changed codes to your original repo on github. 
+    ```bash
+    git push origin devel 
+    ```
+
+### Alternatively: Create a new branch
+
+1. Get your local master up-to-date with upstream/master.
+
+    ```bash
+    cd $working_dir/deepmd-kit
+    git fetch upstream
+    git checkout master
+    git rebase upstream/master
+    ```
+
+2. Create a new branch based on the master branch.
+
+    ```bash
+    git checkout -b new-branch-name
+    ```
+
+3. Modify your codes and design unit tests.
+
+4. Commit your changes
+
+    ```bash
+    git status # Checks the local status
+    git add <file> ... # Adds the file(s) you want to commit. If you want to commit all changes, you can directly use `git add.`
+    git commit -m "commit-message: update the xx"
+    ```
+
+5. Keep your branch in sync with upstream/master
+
+    ```bash
+    # While on your new branch
+    git fetch upstream
+    git rebase upstream/master
+    ```
+
+6. Push your changes to the remote
+
+    ```bash
+    git push -u origin new-branch-name # "-u" is used to track the remote branch from origin
+    ```
+
+### Step 3: Create a pull request
+
+1. Visit your fork at <https://github.com/$username/deepmd-kit> (replace `$username` with your GitHub ID)
+2. Click `pull requests`, followed by `New pull request` and `Compare & pull request` to create your PR.
+
+Now, your PR is successfully submitted! After this PR is merged, you will automatically become a contributor to DeePMD-kit.
+
+## Contact us
+E-mail: contact@deepmodeling.org

README.md

@@ -19,17 +19,15 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r
 
 For more information, check the [documentation](https://deepmd.readthedocs.io/).
 
-## Highlights in DeePMD-kit v2.0
-
-* [Model compression](doc/use-deepmd-kit.md#compress-a-model). Accelerate the efficiency of model inference for 4-15 times.
-* [New descriptors](doc/use-deepmd-kit.md#write-the-input-script). Including [`se_e2_r`](doc/train-se-e2-r.md) and [`se_e3`](doc/train-se-e3.md).
+# Highlights in DeePMD-kit v2.0
+* [Model compression](doc/getting-started.md#compress-a-model). Accelerate the efficiency of model inference for 4-15 times.
+* [New descriptors](doc/getting-started.md#write-the-input-script). Including [`se_e2_r`](doc/train-se-e2-r.md) and [`se_e3`](doc/train-se-e3.md).
 * [Hybridization of descriptors](doc/train-hybrid.md). Hybrid descriptor constructed from concatenation of several descriptors.
 * Atom type embedding.
 * Training and inference the dipole (vector) and polarizability (matrix).
 * Split of training and validation dataset.
 * Optimized training on GPUs. 
 
-
 ## Highlighted features
 * **interfaced with TensorFlow**, one of the most popular deep learning frameworks, making the training process highly automatic and efficient, in addition Tensorboard can be used to visualize training procedure.
 * **interfaced with high-performance classical MD and quantum (path-integral) MD packages**, i.e., LAMMPS and i-PI, respectively. 
@@ -62,19 +60,19 @@ One may manually install DeePMD-kit by following the instuctions on [installing
 
 # Use DeePMD-kit
 
-The typical procedure of using DeePMD-kit includes 5 steps 
+The typical procedure of using DeePMD-kit includes the following steps 
 
-1. [Prepare data](doc/use-deepmd-kit.md#prepare-data)
-2. [Train a model](doc/use-deepmd-kit.md#train-a-model)
+1. [Prepare data](doc/getting-started.md#prepare-data)
+2. [Train a model](doc/getting-started.md#train-a-model)
 3. [Analyze training with Tensorboard](doc/tensorboard.md)
-4. [Freeze the model](doc/use-deepmd-kit.md#freeze-a-model)
-5. [Test the model](doc/use-deepmd-kit.md#test-a-model)
-6. [Compress the model](doc/use-deepmd-kit.md#compress-a-model)
-7. [Inference the model in python](doc/use-deepmd-kit.md#model-inference) or using the model in other molecular simulation packages like [LAMMPS](doc/use-deepmd-kit.md#run-md-with-lammps), [i-PI](doc/use-deepmd-kit.md#run-path-integral-md-with-i-pi) or [ASE](doc/use-deepmd-kit.md#use-deep-potential-with-ase).
+4. [Freeze the model](doc/getting-started.md#freeze-a-model)
+5. [Test the model](doc/getting-started.md#test-a-model)
+6. [Compress the model](doc/getting-started.md#compress-a-model)
+7. [Inference the model in python](doc/getting-started.md#model-inference) or using the model in other molecular simulation packages like [LAMMPS](doc/getting-started.md#run-md-with-lammps), [i-PI](doc/getting-started.md#run-path-integral-md-with-i-pi) or [ASE](doc/getting-started.md#use-deep-potential-with-ase).
 
-A quick-start on using DeePMD-kit can be found [here](doc/use-deepmd-kit.md).
+A quick-start on using DeePMD-kit can be found [here](doc/getting-started.md).
 
-A full [document](doc/train-input.rst) on options in the training input script is available.
+A full [document](doc/train-input-auto.rst) on options in the training input script is available.
 
 
 # Code structure
@@ -97,13 +95,17 @@ The code is organized as follows:
 * `source/op`: tensorflow op implementation. working with library.
 
 
-
 # Troubleshooting
 
-See the [troubleshooting page](doc/troubleshooting.md).
+See the [troubleshooting page](doc/troubleshooting/index.md).
+
+
+# Contributing
+
+See [DeePMD-kit Contributing Guide](CONTRIBUTING.md) to become a contributor! 🤓
 
 
-[1]: http://www.global-sci.com/galley/CiCP-2017-0213.pdf
+[1]: https://arxiv.org/abs/1707.01478
 [2]: https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.120.143001
-[3]:https://arxiv.org/abs/1805.09003
-[4]:https://aip.scitation.org/doi/full/10.1063/1.5027645
+[3]: https://arxiv.org/abs/1805.09003
+[4]: https://aip.scitation.org/doi/full/10.1063/1.5027645

doc/application-examples.md

@@ -6,3 +6,8 @@
 
 ## MD on different hardware platforms
 
+There is a scheme to generate doc html from python scripts provided in the ../examples/ directory, so that each case in doc has a counter part in ../examples.
+
+This scheme is implemented with sphinx-gallery.
+
+Do we want to use this ???

doc/conf.py

@@ -10,10 +10,51 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
+import os
 # import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import recommonmark
+from recommonmark.transform import AutoStructify
 
+def mkindex_troubleshooting():
+    oldfindex = open("troubleshooting/index.md", "r")
+    _oldlist = oldfindex.readlines()
+    oldlist = _oldlist[4:]
+    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()
+
+    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.close()
 
 # -- Project information -----------------------------------------------------
 
@@ -27,12 +68,25 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
+# extensions = [
+#     'recommonmark',
+#     "sphinx_rtd_theme",
+#     'myst_parser',
+#     'sphinx_markdown_tables',
+#     'sphinx.ext.autosummary'
+# ]
+
+mkindex_troubleshooting()
+mkindex_development()
+
 extensions = [
-    'recommonmark',
     "sphinx_rtd_theme",
+    'myst_parser',
     'sphinx.ext.autosummary'
 ]
 
+myst_heading_anchors = 4
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']