From 056ea31dd2c5380af752b5b094dc84fe8cc3659f Mon Sep 17 00:00:00 2001 From: Feroz Hassan <75996466+ferozmay@users.noreply.github.com> Date: Sun, 24 May 2026 19:37:13 +0100 Subject: [PATCH 1/2] docs: migrate from Sphinx to MkDocs material --- .github/workflows/docs.yaml | 16 ++-- docs/Makefile | 20 ----- docs/{source => }/authors.md | 0 docs/{source => }/coarse-graining.md | 0 docs/{source => }/constraints.md | 0 docs/{source => }/energy-model.md | 10 +-- docs/{source => }/getting-started.md | 0 docs/{source => }/github.md | 0 docs/index.md | 4 + docs/javascripts/mathjax.js | 19 ++++ docs/{source => }/license.md | 0 docs/{source/_static => }/logo-qsl.jpeg | Bin docs/make.bat | 35 -------- docs/{source => }/quickstart.md | 0 docs/requirements.txt | 55 +++--------- docs/source/conf.py | 115 ------------------------ docs/source/index.md | 33 ------- gen_ref_pages.py | 43 +++++++++ mkdocs.yml | 90 +++++++++++++++++++ 19 files changed, 180 insertions(+), 260 deletions(-) delete mode 100644 docs/Makefile rename docs/{source => }/authors.md (100%) rename docs/{source => }/coarse-graining.md (100%) rename docs/{source => }/constraints.md (100%) rename docs/{source => }/energy-model.md (91%) rename docs/{source => }/getting-started.md (100%) rename docs/{source => }/github.md (100%) create mode 100644 docs/index.md create mode 100644 docs/javascripts/mathjax.js rename docs/{source => }/license.md (100%) rename docs/{source/_static => }/logo-qsl.jpeg (100%) delete mode 100644 docs/make.bat rename docs/{source => }/quickstart.md (100%) delete mode 100644 docs/source/conf.py delete mode 100644 docs/source/index.md create mode 100644 gen_ref_pages.py create mode 100644 mkdocs.yml diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index cbb6604..30b6332 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -3,6 +3,7 @@ name: Build & Deploy Docs on: push: branches: [ main ] + pull_request: workflow_dispatch: permissions: @@ -12,7 +13,7 @@ permissions: concurrency: group: "pages" - cancel-in-progress: true + cancel-in-progress: false jobs: build: @@ -22,23 +23,24 @@ jobs: - uses: actions/setup-python@v5 with: - python-version: "3.12" + python-version: "3.13" - name: Install docs dependencies run: | python -m pip install --upgrade pip pip install -r docs/requirements.txt - - name: Build Sphinx HTML - run: | - python -m sphinx -b html docs/source docs/build/html + - name: Build site (strict) + run: mkdocs build --strict - name: Upload artifact + if: github.ref == 'refs/heads/main' uses: actions/upload-pages-artifact@v3 with: - path: docs/build/html + path: site deploy: + if: github.ref == 'refs/heads/main' runs-on: ubuntu-latest needs: build environment: @@ -47,4 +49,4 @@ jobs: steps: - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@v4 \ No newline at end of file + uses: actions/deploy-pages@v4 diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d0c3cbf..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/source/authors.md b/docs/authors.md similarity index 100% rename from docs/source/authors.md rename to docs/authors.md diff --git a/docs/source/coarse-graining.md b/docs/coarse-graining.md similarity index 100% rename from docs/source/coarse-graining.md rename to docs/coarse-graining.md diff --git a/docs/source/constraints.md b/docs/constraints.md similarity index 100% rename from docs/source/constraints.md rename to docs/constraints.md diff --git a/docs/source/energy-model.md b/docs/energy-model.md similarity index 91% rename from docs/source/energy-model.md rename to docs/energy-model.md index 6ddee31..8d7d356 100644 --- a/docs/source/energy-model.md +++ b/docs/energy-model.md @@ -53,11 +53,11 @@ Q = np.array([ # quadratic coefficients b_ij (symmetric, model = EnergyModel(n=n, couplings=[q, Q], name="my_qubo", model_type="binary") ``` --> -```{note} -Provide the quadratic term as a **full symmetric matrix with a zero diagonal** (not -upper-triangular): QeMCMC sums over all $i, j$ and halves the result, giving the $\sum_{i { + MathJax.startup.output.clearCache(); + MathJax.typesetClear(); + MathJax.texReset(); + MathJax.typesetPromise(); +}); diff --git a/docs/source/license.md b/docs/license.md similarity index 100% rename from docs/source/license.md rename to docs/license.md diff --git a/docs/source/_static/logo-qsl.jpeg b/docs/logo-qsl.jpeg similarity index 100% rename from docs/source/_static/logo-qsl.jpeg rename to docs/logo-qsl.jpeg diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index dc1312a..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "" goto help - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/source/quickstart.md b/docs/quickstart.md similarity index 100% rename from docs/source/quickstart.md rename to docs/quickstart.md diff --git a/docs/requirements.txt b/docs/requirements.txt index ac8c94a..e873d15 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,45 +1,10 @@ - - -autoapi==2.0.1 -sphinx-autoapi==3.7.0 -sphinx>=8 -sphinx-copybutton==0.5.2 -accessible-pygments==0.0.5 -alabaster==1.0.0 -babel==2.17.0 -beautifulsoup4==4.14.2 -certifi==2025.10.5 -charset-normalizer==3.4.4 -commonmark==0.9.1 -docutils==0.21.2 -furo==2025.9.25 -idna==3.11 -imagesize==1.4.1 -Jinja2==3.1.6 -linkify-it-py==2.0.3 -markdown-it-py==4.0.0 -MarkupSafe==3.0.3 -mdit-py-plugins==0.5.0 -mdurl==0.1.2 -myst-parser==5.0.0 -packaging==25.0 -Pygments==2.19.2 -PyYAML==6.0.3 -recommonmark==0.7.1 -requests==2.32.5 -roman-numerals-py==3.1.0 -snowballstemmer==3.0.1 -soupsieve==2.8 -Sphinx==8.2.3 -sphinx-autodoc-typehints==3.5.2 -sphinx-rtd-theme==3.0.2 -sphinxcontrib-applehelp==2.0.0 -sphinxcontrib-devhelp==2.0.0 -sphinxcontrib-htmlhelp==2.1.0 -sphinxcontrib-jquery==4.1 -sphinxcontrib-jsmath==1.0.1 -sphinxcontrib-qthelp==2.0.0 -sphinxcontrib-serializinghtml==2.0.0 -typing_extensions==4.15.0 -uc-micro-py==1.0.3 -urllib3==2.5.0 +# Documentation toolchain (MkDocs + Material). +# Static analysis only — no need to install the package or its heavy deps. +mkdocs>=1.6 +mkdocs-material>=9.5 +mkdocstrings[python]>=0.26 +mkdocs-gen-files>=0.5 +mkdocs-literate-nav>=0.6 +mkdocs-section-index>=0.3 +mkdocs-include-markdown-plugin>=6.0 +black>=24.0 # formats the auto-generated API signatures diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 03ec502..0000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,115 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# For the full list of built-in configuration values, see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - -import sys -from pathlib import Path - -HERE = Path(__file__).resolve().parent # docs/source - - -def find_repo_root(start: Path) -> Path: - for p in [start, *start.parents]: - if (p / "src" / "qemcmc").is_dir(): - return p - raise RuntimeError("Could not find repo root containing src/qemcmc") - - -REPO_ROOT = find_repo_root(HERE) -SRC = REPO_ROOT / "src" -PKG = SRC / "qemcmc" - -# sys.path.insert(0, os.path.abspath("../../QeMCMC/src")) -sys.path.insert(0, str(SRC)) -autoapi_dirs = [str(PKG)] - -project = "QeMCMC" -copyright = "2025, Feroz Hassan and Stuart Ferguson" -author = "Feroz Hassan" -release = "1.0.0" - - -# AutoAPI configuration -# autoapi_dirs = ["../../QeMCMC/src/qemcmc"] # Path to your source code -autoapi_type = "python" -autoapi_template_dir = "_autoapi_templates" -autoapi_root = "api" -autoapi_add_toctree_entry = True -autoapi_keep_files = False - - -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration - -extensions = [ - "myst_parser", - "sphinx.ext.autodoc", - "sphinx.ext.napoleon", - "sphinx.ext.viewcode", - "sphinx.ext.intersphinx", - "sphinx.ext.autosummary", - "autoapi.extension", - "sphinx_copybutton", -] - - -myst_enable_extensions = [ - "amsmath", - "attrs_inline", - "colon_fence", - "deflist", - "dollarmath", - "fieldlist", - "html_admonition", - "html_image", - "linkify", - "replacements", - "smartquotes", - "strikethrough", - "substitution", - "tasklist", - "smartquotes", -] - -autodoc_default_options = { - "members": True, - "undoc-members": True, - "show-inheritance": True, -} - -autosummary_generate = True - -napoleon_google_docstring = True -napoleon_numpy_docstring = True -napoleon_include_init_with_doc = True - -myst_heading_anchors = 3 - -myst_url_schemes = ("http", "https", "mailto") - - -autosectionlabel_prefix_document = True - -source_suffix = {".rst": "restructuredtext", ".md": "markdown"} - -templates_path = ["_templates"] -exclude_patterns = [] - - -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output - -html_theme = "furo" -html_static_path = ["_static"] - -html_theme_options = { - "logo": { - "text": "Quantum Software Lab", - "image_light": "_static/logo-qsl.jpeg", - "image_dark": "_static/logo-qsl.jpeg", - } -} diff --git a/docs/source/index.md b/docs/source/index.md deleted file mode 100644 index 584487b..0000000 --- a/docs/source/index.md +++ /dev/null @@ -1,33 +0,0 @@ - - - -```{include} ../../README.md -:relative-images: -``` - -```{toctree} -:maxdepth: 2 -:caption: Getting Started - -getting-started -quickstart -energy-model -coarse-graining -constraints -``` - -```{toctree} -:maxdepth: 2 -:caption: Package API Docs - -api/index -``` - -```{toctree} -:maxdepth: 2 -:caption: Development - -github -license -authors -``` \ No newline at end of file diff --git a/gen_ref_pages.py b/gen_ref_pages.py new file mode 100644 index 0000000..0a372ad --- /dev/null +++ b/gen_ref_pages.py @@ -0,0 +1,43 @@ +"""Generate the API reference pages and navigation. + +This is the standard mkdocstrings recipe: it walks ``src/qemcmc`` and creates a +virtual ``reference/`` page for every module, plus a ``SUMMARY.md`` consumed by +the literate-nav plugin. New modules appear automatically with no manual upkeep. +""" + +from pathlib import Path + +import mkdocs_gen_files + +nav = mkdocs_gen_files.Nav() + +root = Path(__file__).parent +src = root / "src" + +for path in sorted(src.rglob("*.py")): + module_path = path.relative_to(src).with_suffix("") + doc_path = path.relative_to(src).with_suffix(".md") + full_doc_path = Path("reference", doc_path) + + parts = tuple(module_path.parts) + + if parts[-1] == "__init__": + parts = parts[:-1] + doc_path = doc_path.with_name("index.md") + full_doc_path = full_doc_path.with_name("index.md") + elif parts[-1] == "__main__": + continue + + if not parts: + continue + + nav[parts] = doc_path.as_posix() + + with mkdocs_gen_files.open(full_doc_path, "w") as fd: + ident = ".".join(parts) + fd.write(f"::: {ident}") + + mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root)) + +with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file: + nav_file.writelines(nav.build_literate_nav()) diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..7993a82 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,90 @@ +site_name: QeMCMC +site_description: Quantum-enhanced Markov Chain Monte Carlo sampler simulated using PennyLane +site_url: https://stuartferguson00.github.io/QeMCMC/ +repo_url: https://github.com/Stuartferguson00/QeMCMC +repo_name: Stuartferguson00/QeMCMC + +theme: + name: material + icon: + logo: material/atom + favicon: logo-qsl.jpeg + features: + - navigation.tabs + - navigation.sections + - navigation.top + - toc.follow + - search.suggest + - search.highlight + - content.code.copy + - content.code.annotate + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: indigo + accent: indigo + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: indigo + accent: indigo + toggle: + icon: material/brightness-4 + name: Switch to light mode + +plugins: + - search + - include-markdown + - gen-files: + scripts: + - gen_ref_pages.py + - literate-nav: + nav_file: SUMMARY.md + - section-index + - mkdocstrings: + handlers: + python: + paths: [src] + options: + docstring_style: numpy + docstring_options: + warn_unknown_params: false + show_root_heading: true + show_source: true + members_order: source + separate_signature: true + merge_init_into_class: true + +markdown_extensions: + - admonition + - attr_list + - md_in_html + - pymdownx.details + - pymdownx.superfences + - pymdownx.inlinehilite + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.arithmatex: + generic: true + - toc: + permalink: true + +extra_javascript: + - javascripts/mathjax.js + - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js + +nav: + - Home: index.md + - Getting Started: + - Installation: getting-started.md + - Quick Start: quickstart.md + - Energy Models: energy-model.md + - Coarse Graining: coarse-graining.md + - Constraints: constraints.md + - API Reference: reference/ + - Development: + - GitHub: github.md + - License: license.md + - Authors: authors.md From 45a28a32b7d1b8e224b9c979bd6b534304980f9a Mon Sep 17 00:00:00 2001 From: Feroz Hassan <75996466+ferozmay@users.noreply.github.com> Date: Sun, 24 May 2026 19:53:12 +0100 Subject: [PATCH 2/2] docs: use atom icon --- docs/favicon.svg | 1 + mkdocs.yml | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 docs/favicon.svg diff --git a/docs/favicon.svg b/docs/favicon.svg new file mode 100644 index 0000000..5b21e3e --- /dev/null +++ b/docs/favicon.svg @@ -0,0 +1 @@ + diff --git a/mkdocs.yml b/mkdocs.yml index 7993a82..18ac65f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: QeMCMC +site_name: QeMCMC documentation site_description: Quantum-enhanced Markov Chain Monte Carlo sampler simulated using PennyLane site_url: https://stuartferguson00.github.io/QeMCMC/ repo_url: https://github.com/Stuartferguson00/QeMCMC @@ -8,7 +8,7 @@ theme: name: material icon: logo: material/atom - favicon: logo-qsl.jpeg + favicon: favicon.svg features: - navigation.tabs - navigation.sections