polish docs references and troubleshooting

.github/workflows/docs.yml

@@ -45,9 +45,7 @@ jobs:
           enable-cache: true
 
       - name: Install dependencies
-        run: |
-          sudo apt update && sudo apt install -y graphviz
-          uv sync --frozen --group docs
+        run: uv sync --frozen --group docs
 
       - name: Build HTML
         run: >

.pre-commit-config.yaml

@@ -31,7 +31,7 @@ repos:
           - .github/common-header.txt
           - --use-current-year
           - --skip-license-insertion-comment
-          - DeepMind
+          - ByteDance Ltd. and/or its affiliates.
   # mypy should run locally to pick up dependencies
   - repo: local
     hooks:

.readthedocs.yaml

@@ -12,12 +12,11 @@ build:
   os: ubuntu-26.04
   tools:
     python: "3.13"
-  apt_packages:
-    - graphviz
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
   configuration: docs/conf.py
+  fail_on_warning: true
 
 # Optionally, but recommended,
 # declare the Python requirements required to build your documentation
@@ -27,3 +26,11 @@ python:
    - method: uv
      command: sync
      groups: [docs]
+
+search:
+  ranking:
+    getting-started/*: 10
+    systems/*: 10
+    guide/*: 5
+    extending/*: 2
+    api-reference/*: -10

README.md

@@ -4,7 +4,7 @@
   <a href="https://codecov.io/github/bytedance/jaqmc"><img src="https://codecov.io/github/bytedance/jaqmc/graph/badge.svg?token=N9QGZFKI6J"></a>
   <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg"></a>
   <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12+-blue.svg"></a>
-  <a href="https://jaqmc.readthedocs.io/latest/"><img src="https://img.shields.io/badge/documentation-teal.svg"></a>
+  <a href="https://jaqmc.readthedocs.io/latest/"><img src="https://app.readthedocs.org/projects/jaqmc/badge/"></a>
 </p>
 
 

docs/_static/custom.css

@@ -77,10 +77,6 @@
     border-color: #fff;
 }
 
-.graphviz {
-    text-align: center;
-}
-
 /* Small config-key badges */
 .sd-badge-sm {
     font-size: 0.65em;

docs/citing.md

@@ -120,7 +120,7 @@ If you enabled `march_beta`, also cite:
 ```
 ````
 
-````{dropdown} Pseudopotential/ECP
+````{dropdown} Semi-local pseudopotential (ECP)
 ```bibtex
 @article{li_fermionic_2022,
   title = {Fermionic Neural Network with Effective Core Potential},

docs/conf.py

@@ -41,13 +41,22 @@
     "protocol_autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.linkcode",
-    "sphinx.ext.graphviz",
     "myst_nb",
+    "mathjax_in_paragraph",
     "sphinx_design",
     "sphinx_autodoc_typehints",
     "sphinx_copybutton",
-    "sphinx_llm.txt",
 ]
+if os.environ.get("READTHEDOCS"):
+    extensions.extend(
+        [
+            "notfound.extension",  # Require absolute URL available in RTD environments
+            "sphinx_llm.txt",  # llms.txt generation is slow. Enabled only in production
+        ]
+    )
+if os.environ.get("GITHUB_WORKFLOW"):
+    extensions.append("sphinx_reredirects")
+    redirects = {"*": "https://jaqmc.readthedocs.io/latest/$source.html"}
 
 templates_path = ["_templates"]
 exclude_patterns = [
@@ -77,6 +86,7 @@
 html_theme_options = {
     "repository_url": "https://github.com/bytedance/jaqmc",
     "use_source_button": True,
+    "path_to_docs": "docs",
     "use_repository_button": True,
     "use_download_button": False,
     "use_edit_page_button": True,
@@ -130,8 +140,6 @@ def linkcode_resolve(domain: str, info):
 nb_execution_in_temp = True
 nb_execution_timeout = 360
 
-graphviz_output_format = "svg"
-
 llms_txt_suffix_mode = "replace"
 
 

docs/config_reference.py

@@ -126,32 +126,6 @@ def _collect_dataclass_descriptions(obj: Any) -> dict[str, str]:
     return descriptions
 
 
-def _compact_description(text: str | None) -> str | None:
-    """Collapse a field description into a short inline sentence.
-
-    Returns:
-        First sentence of the first paragraph, or ``None`` when unavailable.
-    """
-    if not text:
-        return None
-
-    first_paragraph = text.strip().split("\n\n", 1)[0]
-    compact = " ".join(line.strip() for line in first_paragraph.splitlines()).strip()
-    if not compact:
-        return None
-
-    sentence_break = re.search(r"(?<=[.!?])\s+(?=[A-Z(])", compact)
-    if sentence_break:
-        compact = compact[: sentence_break.start()].strip()
-    return compact or None
-
-
-def _compact_resolved_description(text: str | None, mod: object) -> str | None:
-    """Return a compact description with local references resolved."""
-    compact = _compact_description(text)
-    return _resolve_refs(compact, mod) if compact else None
-
-
 def _type_name(t) -> str:
     """Return a plain-text type name without RST markup.
 
@@ -694,7 +668,8 @@ def _description(
         self, descriptions: dict[str, str], name: str, mod: object
     ) -> str | None:
         """Return the compact rendered description for a field or parameter."""
-        return _compact_resolved_description(descriptions.get(name), mod)
+        text = descriptions.get(name)
+        return _resolve_refs(text, mod) if text else None
 
     def _make_item(
         self, entry: ConfigDefaultEntry

docs/extending/custom-components/index.md

@@ -142,7 +142,7 @@ sampler = cfg.get("sampler", MCMCSampler)
 builder.configure_sample_plan(wf.logpsi, {"electrons": sampler})
 ```
 
-This is why the the [Wiring Principles](#wiring-principles) section says "the builder wires what it creates" — it wires components it resolves from config (such as optimizer and writers). You wire estimators yourself, either in the constructor or via `wire()`.
+This is why the [Wiring Principles](#wiring-principles) section says "the builder wires what it creates" — it wires components it resolves from config (such as optimizer and writers). You wire estimators yourself, either in the constructor or via `wire()`.
 
 ## Writing Custom Components
 

docs/getting-started/concepts.md

@@ -19,41 +19,10 @@ This cycle continues for a fixed number of steps. The energy estimate should dec
 
 The VMC training loop is built from four independent components. Each one handles a specific part of the cycle, and each can be swapped via <project:../guide/configuration.md> without touching the others.
 
-```{graphviz}
-digraph {
-    layout=circo
-    node [shape=box, style=rounded]
-
-    E [label=<
-      <table border="0" cellspacing="0" cellpadding="2">
-        <tr><td><b>Estimators</b></td></tr>
-        <tr><td>e.g. local energy</td></tr>
-      </table>
-    >]
-    O [label=<
-      <table border="0" cellspacing="0" cellpadding="2">
-        <tr><td><b>Optimizer</b></td></tr>
-        <tr><td>e.g. KFAC, Adam</td></tr>
-      </table>
-    >]
-    W [label=<
-      <table border="0" cellspacing="0" cellpadding="2">
-        <tr><td><b>Wavefunction</b></td></tr>
-        <tr><td>e.g. FermiNet</td></tr>
-      </table>
-    >]
-    S [label=<
-      <table border="0" cellspacing="0" cellpadding="2">
-        <tr><td><b>Sampler</b></td></tr>
-        <tr><td>e.g. MCMC</td></tr>
-      </table>
-    >]
-
-    W -> S [headlabel="sample from |ψ|²", labeldistance=4, labelangle=-70]
-    S -> E [taillabel="electron positions", labeldistance=4, labelangle=70]
-    E -> O [headlabel="energy gradient", labeldistance=4, labelangle=-70]
-    O -> W [xlabel="updated params"]
-}
+```{image} img/workflow.svg
+:alt: VMC training workflow
+:class: rounded-3
+:align: center
 ```
 
 ### Wavefunction
@@ -76,7 +45,7 @@ $$
 E_L(\mathbf{r}) = \frac{\hat{H}\,\psi(\mathbf{r})}{\psi(\mathbf{r})}
 $$
 
-where $\hat{H}$ is the Hamiltonian and $\mathbf{r}$ is an electron configuration. The local energy is evaluated at each walker position, and its mean over walkers gives the variational energy estimate — the number reported as `energy` in the training output.
+where $\hat{H}$ is the Hamiltonian and $\mathbf{r}$ is an electron configuration. The local energy is evaluated at each walker position, and its mean over walkers gives the variational energy estimate — the quantity recorded as `total_energy` in statistics files and often shown as `loss` or `energy` in terminal summaries.
 
 Estimators also compute individual energy components (kinetic, electron-electron, electron-ion) and can compute non-energy observables like $\langle S^2 \rangle$. Multiple estimators run in a pipeline, and their outputs are written to the training statistics files. See <project:../guide/estimators/index.md> for details.