refactor docs

[njzjz]

See https://explore-deepmd.njzjz.win/ for preview.
PDF: https://explore-deepmd.njzjz.win/_/downloads/en/latest/pdf/

[codecov-commenter]

Codecov Report

Merging #952 (9de2e1e) into devel (72aaa9b) will decrease coverage by 0.14%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##            devel     #952      +/-   ##
==========================================
- Coverage   75.51%   75.37%   -0.15%     
==========================================
  Files          85       85              
  Lines        6796     6801       +5     
==========================================
- Hits         5132     5126       -6     
- Misses       1664     1675      +11     

Impacted Files	Coverage Δ
deepmd/calculator.py	79.41% <0.00%> (-10.25%)	⬇️
deepmd/utils/tabulate.py	86.18% <0.00%> (-1.66%)	⬇️
deepmd/descriptor/se_a.py	96.18% <0.00%> (-1.39%)	⬇️
source/lib/include/neighbor_list.h	100.00% <0.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 72aaa9b...9de2e1e. Read the comment docs.

[amcadmus]

0. The links in the README.md at the deepmd-kit source root are broken.
1. How a user conveniently read the doc locally or from the github website? or we only want to provide the doc through readthedoc?

[njzjz]

How a user conveniently read the doc locally or from the github website? or we only want to provide the doc through readthedoc?

It's hard to support all of them at the same time. However, I can provide a README under doc directory to give a guide how to build the website locally. For GitHub, I think one can easily visit our website if he can visit the GitHub?

[njzjz]

Maybe I can provide a separated catalog for GitHub or Gitee users.

[tuoping]

You can change this:

exhale_args = {
   ...
    "rootFileName":          "api_cc.rst",
   ...
}

to

exhale_args = {
   ...
    "rootFileName":          "../development/api_cc.rst",
   ...
}

Then the automatically built api_cc.rst will be in directory doc/development/

[tuoping]

Also, regarding @amcadmus 's comments, you can have both index.rst and index.md in the same directory, RST will go for index.rst automatically.

[tuoping]

And you can change here to

.. toctree
    :maxdepth: 3
    :caption: Developer Guide
    :glob:

    development/*

[njzjz]

But, sections will be disordered?

[tuoping]

The sections won't change much. Originally, the list was like this

.. toctree::
   :maxdepth: 3
   :caption: Developer Guide

   api
   API_CC/api_cc
   development/coding-conventions
   development/type-embedding

The automatically generated one with ":glob:" is exactly the same.

[tuoping]

For this directory to handle possible changes in the future, may we consider this:

.. toctree::
    :maxdepth: 1
    :caption: trouble shooting
    :glob:

    ./*

[tuoping]

This turned out to work out fine.

[njzjz]

You can change this:

exhale_args = {
   ...
    "rootFileName":          "api_cc.rst",
   ...
}

to

exhale_args = {
   ...
    "rootFileName":          "../development/api_cc.rst",
   ...
}

Then the automatically built api_cc.rst will be in directory doc/development/

Not work. api_cc.rst relies other files.

[tuoping]

This works:

.. toctree::
   :maxdepth: 3
   :caption: Developer Guide
   :glob:

   development/*
   API_CC/api_cc

[tuoping]

The sections will be ordered like this:

Developer Guide

Python API
Coding Conventions
Atom Type Embedding
C++ API

[tuoping]

Preview here:
https://deepmd-kit.readthedocs.io/en/refactor-docs/