QMCPACK · brockdyer03 · May 4, 2026 · Sep 1, 2026 · Sep 1, 2026 · Sep 2, 2026
diff --git a/docs/conf.py b/docs/conf.py
@@ -30,16 +30,25 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-import sys, os
-sys.path.append(os.path.abspath('extensions'))
+import os
+import sys
 
-import sphinx_rtd_theme
+sys.path.append(os.path.abspath('extensions'))
 
-extensions = ['sphinxcontrib.bibtex', "sphinx_rtd_theme"]
+extensions = [
+    "sphinxcontrib.bibtex",
+    "pydata_sphinx_theme",
+    "sphinx_copybutton",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.coverage",
+]
 bibtex_bibfiles = ["bibs/all.bib"]
-
+copybutton_exclude = '.linenos, .gp, .go' # Don't copy line numbers, prompts, or outputs.
 numfig = True
 
+suppress_warnings = ["misc.highlighting_failure"]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -54,7 +63,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'pydata_sphinx_theme'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -64,3 +73,26 @@
 html_css_files = [
     'custom.css',
 ]
+html_theme_options = {
+    "logo": {
+        "alt_text": "QMCPACK",
+        "image_dark": "figs/QMCPACK_logo.png",
+        "image_light": "figs/QMCPACK_logo.png",
+    },
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/QMCPACK/qmcpack",
+            "icon": "fa-brands fa-github",
+        },
+    ],
+    "navbar_end": [
+        "search-button",
+        "theme-switcher",
+        "navbar-icon-links"
+    ],
+    "show_toc_level": 3,
+    "show_nav_level": 4,
+    "navigation_depth": 6,
+    "secondary_sidebar_items": ["page-toc"],
+}
diff --git a/docs/contributing.rst → docs/contributing/contributing.rst b/docs/contributing.rst → docs/contributing/contributing.rst
diff --git a/docs/design_features.rst → docs/contributing/design_features.rst b/docs/design_features.rst → docs/contributing/design_features.rst
diff --git a/docs/developing.rst → docs/contributing/developing.rst b/docs/developing.rst → docs/contributing/developing.rst
diff --git a/docs/external_tools.rst → docs/contributing/external_tools.rst b/docs/external_tools.rst → docs/contributing/external_tools.rst
diff --git a/docs/github_actions.rst → docs/contributing/github_actions.rst b/docs/github_actions.rst → docs/contributing/github_actions.rst
diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
@@ -0,0 +1,15 @@
+.. _contrib-and-devel:
+
+Contributing
+============
+
+.. toctree::
+   :maxdepth: 2
+
+   contributing
+   design_features
+   unit_testing
+   integration_tests
+   github_actions
+   developing
+   external_tools
diff --git a/docs/integration_tests.rst → docs/contributing/integration_tests.rst b/docs/integration_tests.rst → docs/contributing/integration_tests.rst
diff --git a/docs/unit_testing.rst → docs/contributing/unit_testing.rst b/docs/unit_testing.rst → docs/contributing/unit_testing.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -13,43 +13,13 @@ User's Guide and Developer's Manual
 
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    :caption: Contents:
 
-   introduction
-   features
-   citing
-   performance_portable
-   installation
-   running
-   units
-   input_overview
-   simulationcell
-   intro_wavefunction
-   hamiltonianobservable
-   methods
-   output_overview
-   analyzing
-   LCAO
-   sCI
-   spin_orbit
-   afqmc
-   examples
-   lab_qmc_statistics
-   lab_qmc_basics
-   lab_advanced_molecules
-   lab_condensed_matter
-   lab_excited
-   lab_afqmc
-   additional_tools
-   external_tools
-   contributing
-   unit_testing
-   integration_tests
-   github_actions
-   running_docker
-   design_features
-   developing
+   introduction/index
+   user_guide/index
+   labs/index
+   contributing/index
    bibliography
    appendices
 

diff --git a/docs/citing.rst → docs/introduction/citing.rst b/docs/citing.rst → docs/introduction/citing.rst
diff --git a/docs/features.rst → docs/introduction/features.rst b/docs/features.rst → docs/introduction/features.rst
diff --git a/docs/introduction/index.rst b/docs/introduction/index.rst
@@ -0,0 +1,13 @@
+.. _intro:
+
+Introduction
+============
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction
+   features
+   methods
+   performance_portable
+   citing
diff --git a/docs/introduction.rst → docs/introduction/introduction.rst b/docs/introduction.rst → docs/introduction/introduction.rst
diff --git a/docs/methods.rst → docs/introduction/methods.rst b/docs/methods.rst → docs/introduction/methods.rst
diff --git a/docs/performance_portable.rst → docs/introduction/performance_portable.rst b/docs/performance_portable.rst → docs/introduction/performance_portable.rst
diff --git a/docs/lab_afqmc.rst b/docs/lab_afqmc.rst
diff --git a/docs/labs/index.rst b/docs/labs/index.rst
@@ -0,0 +1,15 @@
+.. _labs:
+
+Labs
+====
+
+
+.. toctree::
+   :maxdepth: 2
+
+   lab_qmc_statistics
+   lab_qmc_basics
+   lab_advanced_molecules
+   lab_condensed_matter
+   lab_excited
+   lab_afqmc
diff --git a/docs/lab_advanced_molecules.rst → docs/labs/lab_advanced_molecules.rst b/docs/lab_advanced_molecules.rst → docs/labs/lab_advanced_molecules.rst
diff --git a/docs/labs/lab_afqmc.rst b/docs/labs/lab_afqmc.rst
@@ -0,0 +1,16 @@
+.. _lab-afqmc:
+
+AFQMC Tutorials
+===============
+
+Below we will run through some full AFQMC workflow examples. The necessary scripts can be
+found in the ``qmcpack/examples/afqmc`` directory.
+
+.. include:: ../../examples/afqmc/01-neon_atom/README.rst
+.. include:: ../../examples/afqmc/02-neon_frozen_core/README.rst
+.. include:: ../../examples/afqmc/03-carbon_triplet_uhf/README.rst
+.. include:: ../../examples/afqmc/04-N2_nomsd/README.rst
+.. include:: ../../examples/afqmc/05-N2_phmsd/README.rst
+.. include:: ../../examples/afqmc/06-methane_converge_back_prop/README.rst
+.. include:: ../../examples/afqmc/07-diamond_2x2x2_supercell/README.rst
+.. include:: ../../examples/afqmc/08-diamond_2x2x2_kpoint_sym/README.rst
diff --git a/docs/lab_condensed_matter.rst → docs/labs/lab_condensed_matter.rst b/docs/lab_condensed_matter.rst → docs/labs/lab_condensed_matter.rst
diff --git a/docs/lab_excited.rst → docs/labs/lab_excited.rst b/docs/lab_excited.rst → docs/labs/lab_excited.rst
diff --git a/docs/lab_qmc_basics.rst → docs/labs/lab_qmc_basics.rst b/docs/lab_qmc_basics.rst → docs/labs/lab_qmc_basics.rst
diff --git a/docs/lab_qmc_statistics.rst → docs/labs/lab_qmc_statistics.rst b/docs/lab_qmc_statistics.rst → docs/labs/lab_qmc_statistics.rst
diff --git a/docs/requirements.in b/docs/requirements.in
@@ -1,4 +1,6 @@
 # Specify inequalities for versions; no stronger dependencies known
-sphinx>=7.2.6
-sphinx_rtd_theme>=2.0.0
+sphinx>=8.0.0
+pydata_sphinx_theme>=0.17.1
 sphinxcontrib-bibtex>=2.6.2
+sphinx-design>=0.6.1
+sphinx-copybutton>=0.5.2
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,29 +1,33 @@
-#
-# This file is autogenerated by pip-compile with Python 3.12
-# by the following command:
-#
-#    pip-compile requirements.in
-#
+# This file was autogenerated by uv via the following command:
+#    uv pip compile requirements.in -o requirements.txt
+accessible-pygments==0.0.5
+    # via pydata-sphinx-theme
 alabaster==1.0.0
     # via sphinx
 babel==2.18.0
-    # via sphinx
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
+beautifulsoup4==4.15.0
+    # via pydata-sphinx-theme
 certifi==2026.1.4
     # via requests
 charset-normalizer==3.4.4
     # via requests
 docutils==0.22.4
     # via
     #   pybtex-docutils
+    #   pydata-sphinx-theme
     #   sphinx
-    #   sphinx-rtd-theme
     #   sphinxcontrib-bibtex
 idna==3.15
     # via requests
 imagesize==1.4.1
     # via sphinx
 jinja2==3.1.6
-    # via sphinx
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
 latexcodec==3.0.1
     # via pybtex
 markupsafe==3.0.3
@@ -36,23 +40,35 @@ pybtex==0.25.1
     #   sphinxcontrib-bibtex
 pybtex-docutils==1.0.3
     # via sphinxcontrib-bibtex
+pydata-sphinx-theme==0.21.0
+    # via -r requirements.in
 pygments==2.20.0
-    # via sphinx
+    # via
+    #   accessible-pygments
+    #   pydata-sphinx-theme
+    #   sphinx
 pyyaml==6.0.3
     # via pybtex
 requests==2.33.0
-    # via sphinx
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
 roman-numerals==4.1.0
     # via sphinx
 snowballstemmer==3.0.1
     # via sphinx
+soupsieve==2.9.2
+    # via beautifulsoup4
 sphinx==9.1.0
     # via
     #   -r requirements.in
-    #   sphinx-rtd-theme
+    #   pydata-sphinx-theme
+    #   sphinx-copybutton
+    #   sphinx-design
     #   sphinxcontrib-bibtex
-    #   sphinxcontrib-jquery
-sphinx-rtd-theme==3.1.0
+sphinx-copybutton==0.5.2
+    # via -r requirements.in
+sphinx-design==0.7.0
     # via -r requirements.in
 sphinxcontrib-applehelp==2.0.0
     # via sphinx
@@ -62,13 +78,13 @@ sphinxcontrib-devhelp==2.0.0
     # via sphinx
 sphinxcontrib-htmlhelp==2.1.0
     # via sphinx
-sphinxcontrib-jquery==4.1
-    # via sphinx-rtd-theme
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
 sphinxcontrib-qthelp==2.0.0
     # via sphinx
 sphinxcontrib-serializinghtml==2.0.0
     # via sphinx
+typing-extensions==4.16.0
+    # via beautifulsoup4
 urllib3==2.7.0
     # via requests
diff --git a/docs/additional_tools.rst → docs/user_guide/additional_tools.rst b/docs/additional_tools.rst → docs/user_guide/additional_tools.rst
diff --git a/docs/LCAO.rst → docs/user_guide/advanced_guide/LCAO.rst b/docs/LCAO.rst → docs/user_guide/advanced_guide/LCAO.rst
diff --git a/docs/afqmc.rst → docs/user_guide/advanced_guide/afqmc.rst b/docs/afqmc.rst → docs/user_guide/advanced_guide/afqmc.rst
diff --git a/docs/user_guide/advanced_guide/index.rst b/docs/user_guide/advanced_guide/index.rst
@@ -0,0 +1,12 @@
+.. _advanced-guide:
+
+Advanced User Guide
+===================
+
+.. toctree::
+   :maxdepth: 2
+
+   afqmc
+   LCAO
+   sCI
+   spin_orbit
diff --git a/docs/sCI.rst → docs/user_guide/advanced_guide/sCI.rst b/docs/sCI.rst → docs/user_guide/advanced_guide/sCI.rst
diff --git a/docs/spin_orbit.rst → .../user_guide/advanced_guide/spin_orbit.rst b/docs/spin_orbit.rst → .../user_guide/advanced_guide/spin_orbit.rst
diff --git a/docs/analyzing.rst → docs/user_guide/analyzing.rst b/docs/analyzing.rst → docs/user_guide/analyzing.rst
diff --git a/docs/examples.rst → docs/user_guide/examples.rst b/docs/examples.rst → docs/user_guide/examples.rst
diff --git a/docs/hamiltonianobservable.rst → docs/user_guide/hamiltonianobservable.rst b/docs/hamiltonianobservable.rst → docs/user_guide/hamiltonianobservable.rst
@@ -534,7 +534,7 @@ Estimators are generally not accumulated during wavefunction optimization sectio
 ``estimator`` factory element:
 
   +------------------+----------------------+
-  | parent elements: | ``estimators`` |
+  | parent elements: | ``estimators``       |
   +------------------+----------------------+
   | type selector:   | ``type`` attribute   |
   +------------------+----------------------+

diff --git a/docs/user_guide/index.rst b/docs/user_guide/index.rst
@@ -0,0 +1,21 @@
+.. _user-guide:
+
+User Guide
+==========
+
+.. toctree::
+   :maxdepth: 2
+
+   installation
+   input_overview
+   simulationcell
+   intro_wavefunction
+   hamiltonianobservable
+   running
+   running_docker
+   output_overview
+   analyzing
+   examples
+   units
+   additional_tools
+   advanced_guide/index
diff --git a/docs/input_overview.rst → docs/user_guide/input_overview.rst b/docs/input_overview.rst → docs/user_guide/input_overview.rst
diff --git a/docs/installation.rst → docs/user_guide/installation.rst b/docs/installation.rst → docs/user_guide/installation.rst
diff --git a/docs/intro_wavefunction.rst → docs/user_guide/intro_wavefunction.rst b/docs/intro_wavefunction.rst → docs/user_guide/intro_wavefunction.rst
@@ -604,7 +604,7 @@ Attribute:
 
 ``radfunc`` element:
   attributes for ``type`` = *"Gaussian"*:
-``TBDoc``
+  ``TBDoc``
 
 .. _spo-hybrid:
 

diff --git a/docs/output_overview.rst → docs/user_guide/output_overview.rst b/docs/output_overview.rst → docs/user_guide/output_overview.rst
diff --git a/docs/running.rst → docs/user_guide/running.rst b/docs/running.rst → docs/user_guide/running.rst
diff --git a/docs/running_docker.rst → docs/user_guide/running_docker.rst b/docs/running_docker.rst → docs/user_guide/running_docker.rst
diff --git a/docs/simulationcell.rst → docs/user_guide/simulationcell.rst b/docs/simulationcell.rst → docs/user_guide/simulationcell.rst
diff --git a/docs/units.rst → docs/user_guide/units.rst b/docs/units.rst → docs/user_guide/units.rst