Re-structured Doc (#513)

* check html window

* change index.rst of branch devel

* Re-structured doc

* Re-structured Doc

* Re-structured Doc

* Re-structured Doc

* Re-structured Doc

* Re-structured Doc

* Re-structured Doc

* Set theme jekyll-theme-cayman

* Create index.md

* Re-structured Doc

* Re-structured Doc

* Re-structured index.rst and seperated install.rst into 3 files;
Renamed use-deepmd-kit as getting-started, and changed the contents a little.

* Same as before

* Edited license.rst and credits.rst

* same as before

* Modified pair-style-deepmd syntax part

* Fixed the collapsed table in getting-started#prepare-data by adding extension sphinx-markdown-tables in conf.py

* Added sphinx-markdown-table in requirements.txt

* Modification after Merge

* modified superlinks in getting-started.md

* same

* Something is imperfect with the url. I can't link to #section in another .md file. So I changed all the external links in getting-started.md, and deleted all the #... parts.

* changed LICENSE to url; deleted whatsnew, application-examples and known_issues in index.rst

* corrected subsection links

* testing external section links

* same

* changed all the superlinks in getting-started.md from markdown format to html format

* same

* Update doc/conf.py

Do not use any <tab> in Python files.

Co-authored-by: Jinzhe Zeng <jinzhe.zeng@rutgers.edu>

* Update doc/getting-started.md

Use a publish version instead

Co-authored-by: Jinzhe Zeng <jinzhe.zeng@rutgers.edu>

* added some descriptor/scripts in api.rst; Changed the user names of contributors in credits.rst; Removed install-hardware-platforms; Put URL for GPLv2 in index.rst

* Changed parser from recommonmark to myst, so the header-anchors in getting-started can support both markdown and html links.

* add myst-parser in requirements

* move doc dependence packages from requirements.txt to setup.py

* changed contributor's order in credits.rst

* change whatsnew

* change highlights in 2.0 in README.md

* Update README.md

Testing README.md

* Add CONTRIBUTING.md
including
    "what you can contribute"
    "before you contribute": "overview of deepmd-kit" (branches) and "developer guide" (Link to "doc/development/index")
    "how to contribute": fork, clone, change, unittest, commit and PR

Made directories troubleshooting and development, so that it's easier for everyone to PR.

Added roadmap.md in doc to list optional commissions for future contributors.

Removed highlights in doc, and added in README.

Removed empty file known_issues.md

* Fixed some minor mistakes.
PS: All the links to repo community are futile yet.

* changed document for training inputs from train-input.rst to train-input-auto.rst (train-input.rst is basically emplty).

* Fixed links under "highlights in kit2.0.0".

* Checked all the links, and made sure they work both in markdown mode and html mode. Especially the ones in README.md and CONTRIBUTING.md

* Sorry, fixed a broken link in CONTRIBUTING.md.

* Asigned language 'bash' for codes in CONTRIBUTING.md; Corrected a typo in README.md

* Update CONTRIBUTING.md

* fix typo in README.md

Co-authored-by: Jinzhe Zeng <jinzhe.zeng@rutgers.edu>

* Update README.md

* Update credits.rst

Not all contributors are core contributor

Co-authored-by: Jinzhe Zeng <jinzhe.zeng@rutgers.edu>
Co-authored-by: tuoping <abby@DESKTOP-LV5KL0D.localdomain>
Co-authored-by: Han Wang <amcadmus@gmail.com>

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']