chore: add mdformat for markdown (#1866)

Sync pre-commit config from
deepmd-kit@69eb0c3bb10be0ace823a5240c9fef6d0bb26c08

Changes:
- Add mdformat for markdown formatting
- Add mdformat plugins: myst, ruff, web, config, beautysh, gfm-alerts

Authored by OpenClaw (model: glm-5)

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

* **Documentation**
* Widespread formatting and clarity improvements across guides,
tutorials, troubleshooting, and examples; expanded and standardized
JSON/YAML samples and workflow explanations for init, relaxation,
property, refine, reproduce, and run processes.

* **Chores**
* Added a Markdown formatter to pre-commit hooks and set CI autoupdate
branch.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

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

Author: 3 people

.pre-commit-config.yaml

@@ -39,3 +39,19 @@ repos:
     hooks:
     - id: velin
       args: ["--write"]
+# markdown
+-   repo: https://github.com/hukkin/mdformat
+    rev: 1.0.0
+    hooks:
+    -   id: mdformat
+        exclude: "^(tests/|examples/init/abacus/).*$"
+        additional_dependencies:
+        # See https://github.com/executablebooks/mdformat-myst/issues/13
+        - "git+https://github.com/njzjz-bothub/mdformat-myst@d9c414e#egg=mdformat-myst"
+        - mdformat-ruff==0.1.3
+        - mdformat-web==0.2.0
+        - mdformat-config==0.2.1
+        - mdformat-beautysh==1.0.0
+        - mdformat-gfm-alerts==2.0.0
+ci:
+  autoupdate_branch: devel

AGENTS.md

@@ -7,6 +7,7 @@ Always reference these instructions first and fallback to search or bash command
 ## Working Effectively
 
 ### Bootstrap and Install
+
 - **Environment Setup**:
   - Ensure Python 3.9+ is available: `python --version`
   - Create virtual environment: `python -m venv dpgen_env && source dpgen_env/bin/activate`
@@ -16,25 +17,29 @@ Always reference these instructions first and fallback to search or bash command
   - Test installation: `dpgen -h`
 
 ### Core Dependencies Installation Times
+
 - **Dependencies**: Include large scientific packages (numpy, pymatgen, ASE, etc.)
 - **Installation Time**: Full installation takes 1-5 minutes with uv, 3-10 minutes with pip. Use timeout of 10+ minutes.
 - If network timeouts occur, retry with: `uv pip install --timeout 600 -e .` or `pip install --timeout 600 -e .`
 - For faster testing: `uv pip install --no-deps -e .` or `pip install --no-deps -e .` (installs without dependencies, will fail at runtime)
 
 ### Testing
+
 - **Unit Tests**: `python -m unittest discover tests -v` -- takes 2-5 minutes. Set timeout to 10+ minutes.
 - **Coverage**: `coverage run --source=./dpgen -m unittest -v && coverage report` -- takes 3-8 minutes. Set timeout to 15+ minutes.
-- **Quick Test**: `python -m unittest tests.test_load_file -v` -- takes <1 second (will fail without dependencies but tests framework)
+- **Quick Test**: `python -m unittest tests.test_load_file -v` -- takes \<1 second (will fail without dependencies but tests framework)
 - **CLI Test**: `python -m unittest tests.test_cli -v` -- tests all dpgen subcommands
 
 ### Build Process
+
 - **No Traditional Build**: This is a pure Python package using setuptools
 - **Documentation Build**: `cd doc && make html` -- takes 2-5 minutes. Set timeout to 10+ minutes.
 - **Package Build**: `python -m build` -- takes 1-3 minutes
 
 ## Development Requirements
 
 ### Commit Messages and PR Titles
+
 - **Use Semantic Commit Messages**: Follow conventional commit format for all commits and PR titles
   - `feat:` for new features
   - `fix:` for bug fixes
@@ -45,6 +50,7 @@ Always reference these instructions first and fallback to search or bash command
   - Examples: `feat: add comprehensive GitHub Copilot instructions`, `fix: resolve timeout in dependency installation`
 
 ### Package Management
+
 - **Prefer uv**: Use `uv` for Python dependency management when available
   - Installation: `uv pip install -e .`
   - Adding dependencies: `uv add package-name`
@@ -53,20 +59,23 @@ Always reference these instructions first and fallback to search or bash command
 ## Main Workflows and Commands
 
 ### dpgen run - Core Workflow
+
 - **Purpose**: Main deep potential generation with iterative training/exploration/labeling
 - **Usage**: `dpgen run param.json machine.json`
 - **Key Files**:
   - `param.json`: System parameters, training config, exploration settings
   - `machine.json`: HPC/computation resource configuration
 - **Process**: Creates iterations (iter.000001, iter.000002, etc.) with 00.train, 01.model_devi, 02.fp subdirectories
 
-### dpgen init_* - Data Preparation
+### dpgen init\_\* - Data Preparation
+
 - **init_bulk**: `dpgen init_bulk param.json [machine.json]` -- bulk systems
 - **init_surf**: `dpgen init_surf param.json [machine.json]` -- surface systems
 - **init_reaction**: `dpgen init_reaction param.json [machine.json]` -- reactive systems
 - **Purpose**: Generate initial training data for deep potential models
 
 ### dpgen autotest - Validation
+
 - **Usage**: `dpgen autotest make|run|post param.json [machine.json]`
 - **Three Phases**:
   - `make`: Set up calculation tasks
@@ -75,17 +84,20 @@ Always reference these instructions first and fallback to search or bash command
 - **Supports**: VASP, ABACUS, DeepMD, MEAM, EAM force fields
 
 ### dpgen simplify - Dataset Optimization
+
 - **Usage**: `dpgen simplify param.json machine.json`
 - **Purpose**: Reduce dataset size while maintaining quality
 
 ### Other Commands
+
 - **collect**: `dpgen collect JOB_DIR OUTPUT` -- gather generated data
 - **db**: `dpgen db param.json` -- database operations
 - **gui**: `dpgen gui` -- web interface (requires dpgui package)
 
 ## Configuration Files
 
 ### Parameter Files (param.json)
+
 - **Location**: `examples/` directory contains templates for different scenarios
 - **Key Examples**:
   - `examples/run/deprecated/dp2.x-lammps-vasp/param.json` -- VASP with LAMMPS
@@ -95,6 +107,7 @@ Always reference these instructions first and fallback to search or bash command
 - **Format**: JSON with extensive nested parameters for system, training, exploration settings
 
 ### Machine Files (machine.json)
+
 - **Location**: `examples/machine/` directory
 - **Purpose**: Define computational resources (HPC systems, cloud platforms)
 - **Examples**:
@@ -105,11 +118,13 @@ Always reference these instructions first and fallback to search or bash command
 ## Validation
 
 ### Always Run Before Committing
+
 - **Full Dependencies Required**: All validation requires `uv pip install -e .` or `pip install -e .` (1-5 min install)
 - `python -m unittest discover tests -v` -- full test suite (requires dependencies)
 - `dpgen -h && dpgen run -h && dpgen autotest -h` -- CLI validation (requires installation)
 
 ### Working Without Full Installation
+
 - **Code Exploration**: All source code can be read and edited without installation
 - **Local Import Test**: `python -c "import sys; sys.path.insert(0, '.'); import dpgen"` (0.03s)
 - **JSON Examples**: Configuration files in `examples/` can be examined without running
@@ -119,6 +134,7 @@ Always reference these instructions first and fallback to search or bash command
 ## Repository Structure
 
 ### Key Directories
+
 - `dpgen/` -- Main source code
   - `generator/` -- Core DP-GEN functionality (`dpgen run`)
   - `auto_test/` -- Testing framework (`dpgen autotest`)
@@ -130,6 +146,7 @@ Always reference these instructions first and fallback to search or bash command
 - `doc/` -- Sphinx documentation
 
 ### Important Files
+
 - `pyproject.toml` -- Modern Python packaging configuration
 - `.github/workflows/test.yml` -- CI pipeline (Python 3.9, 3.12)
 - `dpgen/main.py` -- CLI command definitions and entry points
@@ -139,17 +156,20 @@ Always reference these instructions first and fallback to search or bash command
 ## Common Development Tasks
 
 ### Adding New Features
+
 - **Main CLI**: Edit `dpgen/main.py` to add new subcommands
 - **Core Logic**: Extend modules in `dpgen/generator/`, `dpgen/auto_test/`, etc.
 - **Tests**: Add corresponding tests in `tests/` directory
 - **Examples**: Provide configuration examples in `examples/`
 
 ### Code Quality
+
 - **Linting**: Uses ruff configuration in pyproject.toml
 - **Import Style**: isort with black profile
 - **Documentation**: Numpy-style docstrings, Sphinx for docs
 
 ### Working with Scientific Dependencies
+
 - **Heavy Dependencies**: Package integrates with VASP, LAMMPS, Gaussian, etc.
 - **File I/O**: Uses dpdata for structure file handling
 - **HPC Integration**: dpdispatcher for job submission/management
@@ -160,17 +180,19 @@ Always reference these instructions first and fallback to search or bash command
 - **Installation**: 1-5 minutes with uv, 3-10 minutes with pip (timeout 10+ minutes)
 - **Full Test Suite**: 2-5 minutes (timeout 10+ minutes)
 - **Documentation Build**: 2-5 minutes (timeout 10+ minutes)
-- **Quick Import Test**: <1 second
+- **Quick Import Test**: \<1 second
 - **CI Pipeline**: Runs on Python 3.9 and 3.12, full cycle ~10-15 minutes
 
 ## Error Patterns
 
 ### Common Installation Issues
+
 - **Network Timeouts**: Scientific packages are large, increase pip timeout
 - **Missing System Dependencies**: Some packages require system libraries
 - **Version Conflicts**: Pin to specific Python versions (3.9-3.12)
 
 ### Runtime Issues
+
 - **Missing Dependencies**: Many features require specific scientific software
 - **Configuration Errors**: JSON files have complex nested schemas
 - **HPC Connectivity**: Machine files require proper authentication setup

README.md

@@ -1,6 +1,6 @@
 <picture><source media="(prefers-color-scheme: dark)" srcset="./doc/_static/logo-dark.svg"><source media="(prefers-color-scheme: light)" srcset="./doc/_static/logo.svg"><img alt="DP-GEN logo" src="./doc/_static/logo.svg"></picture>
 
---------------------------------------------------------------------------------
+______________________________________________________________________
 
 # DP-GEN: A concurrent learning platform for the generation of reliable deep learning based potential energy models
 
@@ -10,16 +10,17 @@
 [![conda install](https://img.shields.io/conda/dn/conda-forge/dpgen?label=conda%20install)](https://anaconda.org/conda-forge/dpgen)
 [![pip install](https://img.shields.io/pypi/dm/dpgen?label=pip%20install)](https://pypi.org/project/dpgen)
 
-DP-GEN (Deep Potential GENerator) is a software written in Python, delicately designed to generate a deep learning based model of interatomic potential energy and force field. DP-GEN is dependent on [DeePMD-kit](https://github.com/deepmodeling/deepmd-kit/). With highly scalable interface with common softwares for molecular simulation, DP-GEN is capable to  automatically prepare scripts and maintain job queues on HPC machines (High Performance Cluster) and analyze results.
+DP-GEN (Deep Potential GENerator) is a software written in Python, delicately designed to generate a deep learning based model of interatomic potential energy and force field. DP-GEN is dependent on [DeePMD-kit](https://github.com/deepmodeling/deepmd-kit/). With highly scalable interface with common softwares for molecular simulation, DP-GEN is capable to automatically prepare scripts and maintain job queues on HPC machines (High Performance Cluster) and analyze results.
 
 If you use this software in any publication, please cite:
 
 Yuzhi Zhang, Haidi Wang, Weijie Chen, Jinzhe Zeng, Linfeng Zhang, Han Wang, and Weinan E, DP-GEN: A concurrent learning platform for the generation of reliable deep learning based potential energy models, Computer Physics Communications, 2020, 253, 107206.
 
 ## Highlighted features
-+ **Accurate and efficient**: DP-GEN is capable to sample more than tens of million structures and select only a few for first principles calculation. DP-GEN will finally obtain a uniformly accurate model.
-+ **User-friendly and automatic**: Users may install and run DP-GEN easily. Once successfully running, DP-GEN can dispatch and handle all jobs on HPCs, and thus there's no need for any personal effort.
-+ **Highly scalable**: With modularized code structures, users and developers can easily extend DP-GEN for their most relevant needs. DP-GEN currently supports for HPC systems ([Slurm](https://slurm.schedmd.com/), [PBS](https://www.openpbs.org/), LSF and cloud machines), Deep Potential interface with DeePMD-kit, MD interface with [LAMMPS](https://www.lammps.org/), [Gromacs](http://www.gromacs.org/), [AMBER](https://ambermd.org/), Calypso and *ab-initio* calculation interface with [VASP](https://www.vasp.at/), [PWSCF](https://www.quantum-espresso.org/), [CP2K](https://www.cp2k.org/), [SIESTA](https://departments.icmab.es/leem/siesta/), [Gaussian](https://gaussian.com/), Abacus, [PWmat](http://www.pwmat.com/), etc. We're sincerely welcome and embraced to users' contributions, with more possibilities and cases to use DP-GEN.
+
+- **Accurate and efficient**: DP-GEN is capable to sample more than tens of million structures and select only a few for first principles calculation. DP-GEN will finally obtain a uniformly accurate model.
+- **User-friendly and automatic**: Users may install and run DP-GEN easily. Once successfully running, DP-GEN can dispatch and handle all jobs on HPCs, and thus there's no need for any personal effort.
+- **Highly scalable**: With modularized code structures, users and developers can easily extend DP-GEN for their most relevant needs. DP-GEN currently supports for HPC systems ([Slurm](https://slurm.schedmd.com/), [PBS](https://www.openpbs.org/), LSF and cloud machines), Deep Potential interface with DeePMD-kit, MD interface with [LAMMPS](https://www.lammps.org/), [Gromacs](http://www.gromacs.org/), [AMBER](https://ambermd.org/), Calypso and *ab-initio* calculation interface with [VASP](https://www.vasp.at/), [PWSCF](https://www.quantum-espresso.org/), [CP2K](https://www.cp2k.org/), [SIESTA](https://departments.icmab.es/leem/siesta/), [Gaussian](https://gaussian.com/), Abacus, [PWmat](http://www.pwmat.com/), etc. We're sincerely welcome and embraced to users' contributions, with more possibilities and cases to use DP-GEN.
 
 ## Download and Install
 
@@ -39,24 +40,25 @@ dpgen -h
 
 DP-GEN contains the following workflows:
 
-* [`dpgen run`](https://docs.deepmodeling.com/projects/dpgen/en/latest/run/): Main process of Deep Potential Generator.
-* [Init](https://docs.deepmodeling.com/projects/dpgen/en/latest/init/): Generating initial data.
-  * `dpgen init_bulk`: Generating initial data for bulk systems.
-  * `dpgen init_surf`: Generating initial data for surface systems.
-  * `dpgen init_reaction`: Generating initial data for reactive systems.
-* [`dpgen simplify`](https://docs.deepmodeling.com/projects/dpgen/en/latest/simplify/): Reducing the amount of existing dataset.
-* [`dpgen autotest`](https://docs.deepmodeling.com/projects/dpgen/en/latest/autotest/): Autotest for Deep Potential.
+- [`dpgen run`](https://docs.deepmodeling.com/projects/dpgen/en/latest/run/): Main process of Deep Potential Generator.
+- [Init](https://docs.deepmodeling.com/projects/dpgen/en/latest/init/): Generating initial data.
+  - `dpgen init_bulk`: Generating initial data for bulk systems.
+  - `dpgen init_surf`: Generating initial data for surface systems.
+  - `dpgen init_reaction`: Generating initial data for reactive systems.
+- [`dpgen simplify`](https://docs.deepmodeling.com/projects/dpgen/en/latest/simplify/): Reducing the amount of existing dataset.
+- [`dpgen autotest`](https://docs.deepmodeling.com/projects/dpgen/en/latest/autotest/): Autotest for Deep Potential.
 
 For detailed usage and parameters, read [DP-GEN documentation](https://docs.deepmodeling.com/projects/dpgen/).
 
 ## Tutorials and examples
 
-* [Tutorials](https://tutorials.deepmodeling.com/en/latest/Tutorials/DP-GEN/): basic tutorials for DP-GEN.
-* [Examples](examples): input files in [JSON](https://docs.python.org/3/library/json.html) format.
-* [Publications](https://blogs.deepmodeling.com/papers/dpgen/): Published research articles using DP-GEN.
-* [User guide](https://docs.deepmodeling.com/projects/dpgen/en/latest/user-guide/): frequently asked questions listed in troubleshooting.
+- [Tutorials](https://tutorials.deepmodeling.com/en/latest/Tutorials/DP-GEN/): basic tutorials for DP-GEN.
+- [Examples](examples): input files in [JSON](https://docs.python.org/3/library/json.html) format.
+- [Publications](https://blogs.deepmodeling.com/papers/dpgen/): Published research articles using DP-GEN.
+- [User guide](https://docs.deepmodeling.com/projects/dpgen/en/latest/user-guide/): frequently asked questions listed in troubleshooting.
 
 ## License
+
 The project dpgen is licensed under [GNU LGPLv3.0](./LICENSE).
 
 ## Contributing