Fix DPA-ADAPT docs and backend helpers

Author: zhaiwenxi

doc/cli.rst

@@ -3,7 +3,21 @@
 Command line interface
 ======================
 
+DeePMD-kit ``dp`` command
+-------------------------
+
 .. argparse::
    :module: deepmd.tf.entrypoints.main
    :func: main_parser
    :prog: dp
+
+DPA-ADAPT command line interface
+--------------------------------
+
+The ``dpaad`` command is a short alias for ``dpa-adapt`` and exposes the same
+subcommands and options.
+
+.. argparse::
+   :module: dpa_adapt.cli
+   :func: get_parser
+   :prog: dpa-adapt

doc/dpa_adapt/README.md

@@ -14,6 +14,12 @@ Installs `scikit-learn`, `dpdata`, `ase`, `rdkit`, and `e3nn` alongside DeePMD-k
 
 For a complete runnable example (QM9 HOMO–LUMO gap, ~5 min on CPU), see [`../../examples/dpa_adapt/`](../../examples/dpa_adapt/).
 
+```{toctree}
+:maxdepth: 2
+
+input_formats
+```
+
 ## Fine-tuning strategies
 
 The strategy is the core choice. All four share the same pre-trained DPA backbone and differ in how much of it gets updated:

doc/index.rst

@@ -44,7 +44,6 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r
    test/index
    inference/index
    dpa_adapt/README
-   dpa_adapt/input_formats
    cli
    third-party/index
    agent-skills

dpa_adapt/__init__.py

@@ -9,25 +9,6 @@
 
 __version__ = "0.1.0"
 
-__all__ = [
-    "ConditionManager",
-    "DPAConditionError",
-    "DPAFineTuner",
-    "DPAPredictor",
-    "DPATrainer",
-    "MFTFineTuner",
-    "SmilesDataResult",
-    "attach_labels",
-    "check_data",
-    "convert",
-    "cross_validate",
-    "extract_descriptors",
-    "formula_to_npy",
-    "load_dataset",
-    "smiles_to_npy",
-    "train_test_split",
-]
-
 _LAZY = {
     "ConditionManager": (".conditions", "ConditionManager"),
     "DPAConditionError": (".conditions", "DPAConditionError"),
@@ -47,6 +28,8 @@
     "DPATrainer": (".trainer", "DPATrainer"),
 }
 
+__all__ = list(_LAZY)
+
 
 def __getattr__(name: str):
     if name in _LAZY:

dpa_adapt/_backend.py

@@ -29,12 +29,19 @@ def resolve_dp_command() -> str:
     import os as _os
     import shutil as _shutil
     import sys as _sys
+    import sysconfig as _sysconfig
     from pathlib import Path as _Path
 
     exe_name = "dp.exe" if _os.name == "nt" else "dp"
-    candidate = _Path(_sys.executable).resolve().parent / exe_name
-    if candidate.is_file():
-        return _os.fspath(candidate)
+    scripts_dir = _sysconfig.get_path("scripts")
+    candidates = [
+        _Path(_sys.executable).parent / exe_name,
+    ]
+    if scripts_dir:
+        candidates.append(_Path(scripts_dir) / exe_name)
+    for candidate in candidates:
+        if candidate.is_file():
+            return _os.fspath(candidate)
 
     found = _shutil.which("dp")
     if found:

dpa_adapt/data/__init__.py

@@ -6,24 +6,6 @@
 dpdata, torch, or rdkit.
 """
 
-__all__ = [
-    "DPADataError",
-    "Issue",
-    "SmilesDataResult",
-    "attach_labels",
-    "check_data",
-    "convert",
-    "formula_to_npy",
-    "load_data",
-    "load_dataset",
-    "read_checkpoint_type_map",
-    "read_data_type_map_union",
-    "read_mol_coords",
-    "smiles_to_3d_coords",
-    "smiles_to_npy",
-    "validate_type_map_subset",
-]
-
 _LAZY = {
     "load_data": (".loader", "load_data"),
     "load_dataset": (".dataset", "load_dataset"),
@@ -44,6 +26,8 @@
     "records_from_direct_data": (".smiles", "records_from_direct_data"),
 }
 
+__all__ = list(_LAZY)
+
 
 def __getattr__(name: str):
     if name in _LAZY:

source/tests/dpa_adapt/test_backend_contract.py

@@ -249,6 +249,50 @@ def test_forward_common_fails_without_grad(self, _extractor):
 class TestBackendHelpers:
     """Unit-level checks for _backend utility functions."""
 
+    def test_resolve_dp_command_keeps_symlinked_venv_scripts(self, tmp_path, monkeypatch):
+        import os
+        import sys
+        from pathlib import (
+            Path,
+        )
+
+        from dpa_adapt._backend import (
+            resolve_dp_command,
+        )
+
+        exe_name = "dp.exe" if os.name == "nt" else "dp"
+        python_name = "python.exe" if os.name == "nt" else "python"
+
+        real_bin = tmp_path / "real" / "bin"
+        venv_bin = tmp_path / "venv" / "bin"
+        real_bin.mkdir(parents=True)
+        venv_bin.mkdir(parents=True)
+
+        real_python = real_bin / python_name
+        real_python.write_text("")
+        symlink_python = venv_bin / python_name
+        symlink_python.write_text("")
+
+        wrong_dp = real_bin / exe_name
+        wrong_dp.write_text("")
+        expected_dp = venv_bin / exe_name
+        expected_dp.write_text("")
+
+        def _fake_resolve(self):
+            if self == symlink_python:
+                return real_python
+            return self
+
+        monkeypatch.setattr(Path, "resolve", _fake_resolve)
+        monkeypatch.setattr(sys, "executable", os.fspath(symlink_python))
+        monkeypatch.setattr(
+            "sysconfig.get_path",
+            lambda name: os.fspath(tmp_path / "other") if name == "scripts" else "",
+        )
+        monkeypatch.setattr("shutil.which", lambda name: None)
+
+        assert resolve_dp_command() == os.fspath(expected_dp)
+
     def test_get_torch_device_returns_device(self):
         import sys
         from unittest.mock import (