docs: migrate admonitions to GFM alerts (#5886)

## Summary

- enable the MyST `alert` extension and require MyST-Parser 5.1.0 with
Sphinx 8+
- migrate 83 fenced admonitions across 54 Markdown files to GitHub-style
alerts while preserving nested directives
- map the former `danger` admonitions to GFM `CAUTION` alerts
- align the documentation Python environment with the MyST-Parser 5.1
requirement

## Validation

- `ruff check .`
- `ruff format --check .`
- `mdformat` pre-commit hook
- representative Sphinx HTML build with MyST-Parser 5.1.0 and myst-nb
1.4.0
- TOML and YAML parsing
- alert migration count and legacy directive checks
- `git diff --check`

Reference:
- executablebooks/MyST-Parser#1128

Coding agent: Codex
Codex version: codex-cli 0.144.6
Model: gpt-5.6-sol
Reasoning effort: xhigh

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Documentation**
* Standardized notes, warnings, cautions, and important notices across
the documentation for clearer, more consistent rendering.
* Expanded DPA-2 guidance for graph-based inference, evaluation,
training, legacy routing, and cutoff smoothness.
* Clarified documentation build requirements, including Python 3.11+,
Sphinx 8, MyST-Parser 5.1, and Doxygen.
* **Chores**
* Updated the documentation environment and tooling requirements to
current supported versions.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: njzjz-bot <njzjz.bot@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

doc/README

@@ -1 +1,3 @@
-To run the HTML documentation build, doxygen have to be installed.
+Building the documentation requires Python 3.11 or newer because the `docs`
+extra uses MyST-Parser 5.1 and Sphinx 8. Doxygen must also be installed to build
+the HTML documentation.

doc/backend.md

@@ -45,9 +45,8 @@ The `.pd` extension is used for model checkpoint storage, which is commonly util
 
 ### DP {{ dpmodel_icon }}
 
-:::{note}
-This backend is only for development and should not take into production.
-:::
+> [!NOTE]
+> This backend is only for development and should not take into production.
 
 - Model filename extension: `.dp`, `.yaml`, `.yml`
 

doc/conf.py

@@ -201,6 +201,7 @@
     "https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.2.0/es5/tex-mml-chtml.min.js"
 )
 myst_enable_extensions = [
+    "alert",
     "dollarmath",
     "colon_fence",
     "substitution",

doc/data/system.md

@@ -50,9 +50,8 @@ In general, we always use the following convention of units:
 
 ## Mixed type
 
-:::{note}
-Only the [DPA-1](../model/train-se-atten.md) and [DPA-2](../model/dpa2.md) descriptors support this format.
-:::
+> [!NOTE]
+> Only the [DPA-1](../model/train-se-atten.md) and [DPA-2](../model/dpa2.md) descriptors support this format.
 
 In the standard data format, only those frames with the same fingerprint (i.e. the number of atoms of different elements) can be put together as a unified system.
 This may lead to sparse frame numbers in those rare systems.

doc/development/create-a-model-pt.md

@@ -1,10 +1,9 @@
 # Create a model in other backends {{ pytorch_icon }} {{ dpmodel_icon }}
 
-:::{note}
-**Supported backends**: PyTorch {{ pytorch_icon }}, DP {{ dpmodel_icon }}
-
-In the following context, we use the PyTorch backend as the example, while it also applies to other backends listed above.
-:::
+> [!NOTE]
+> **Supported backends**: PyTorch {{ pytorch_icon }}, DP {{ dpmodel_icon }}
+>
+> In the following context, we use the PyTorch backend as the example, while it also applies to other backends listed above.
 
 If you'd like to create a new model that isn't covered by the existing DeePMD-kit library, but reuse DeePMD-kit's other efficient modules such as data processing, trainer, etc, you may want to read this section.
 

doc/development/type-embedding.md

@@ -86,6 +86,5 @@ build -> _pass_filter -> _filter -> _filter_lower
 
 In `fitting net`, it takes the descriptor vector as input, whose dimension is \[natoms, $M_1\times M_2$\]. Because we need to involve information on the centric atom in this step, we need to generate a matrix named `atype_embed` (of dim [natoms, nchanl]), in which each row is the type embedding vector of the specific centric atom. The input is sorted by type of centric atom, we also know the number of a particular atom type (stored in `natoms[2+i]`), thus we get the type vector of the centric atom. In the build phase of the fitting net, it will check whether type embedding exists in `input_dict` and fetch them. After that, call `embed_atom_type` function to look up the embedding vector for the type vector of the centric atom to obtain `atype_embed`, and concat input with it ([input, atype_embed]). The modified input goes through `fitting` net\` to get predicted energy.
 
-:::{note}
-You can't apply the compression method while using atom-type embedding.
-:::
+> [!NOTE]
+> You can't apply the compression method while using atom-type embedding.

doc/env.md

@@ -1,8 +1,7 @@
 # Runtime environment variables
 
-:::{note}
-For build-time environment variables, see [Install from source code](./install/install-from-source.md).
-:::
+> [!NOTE]
+> For build-time environment variables, see [Install from source code](./install/install-from-source.md).
 
 ## All interfaces
 

doc/environment.yml

@@ -4,7 +4,7 @@ channels:
   - defaults
 dependencies:
   - doxygen>=1.9.1
-  - python=3.10
+  - python=3.11
   - pip>=20.1
   - pip:
       - ..[docs,cpu,torch]

doc/freeze/compress.md

@@ -1,8 +1,7 @@
 # Compress a model {{ tensorflow_icon }} {{ pytorch_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}
 
 ## Theory
 

doc/inference/cxx.md

@@ -1,8 +1,7 @@
 # C/C++ interface
 
-:::{note}
-See [Environment variables](../env.md) for the runtime environment variables.
-:::
+> [!NOTE]
+> See [Environment variables](../env.md) for the runtime environment variables.
 
 ## C++ interface