migrate docs

[knaaptime]

the docs take forever to execute so the user guide could be pruned a bit. Also the raster notebook errors out because Copernicus now requires registration. Would be nice to have a non-US example, but might have to remove that one

[knaaptime]

oops i didnt mean to hit that copilot review. oh well

[Copilot]

Pull request overview

Migrates the documentation site to a new Sphinx setup (MyST + sphinx-immaterial), reorganizes the user guide around in-repo notebooks, and updates the docs build/publish workflow to support versioned deployments.

Changes:

• Replace the legacy docs/ Sphinx layout with docs/source/ (MyST, new theme, new toctrees).
• Move/introduce multiple user-guide notebooks under docs/source/user-guide/.
• Update GitHub Actions docs workflow to build PR artifacts and publish versioned/stable/dev docs; add a helper script for versions.json.

Reviewed changes

Copilot reviewed 27 out of 44 changed files in this pull request and generated 17 comments.

Show a summary per file

File	Description
pyproject.toml	Adds sphinx-immaterial to the docs extras.
docs/update_version_json.py	Adds a helper script to update versions.json for the version switcher.
docs/tutorial.rst (deleted)	Removes old tutorial toctree entry.
docs/source/user-guide/dot_density_example.ipynb	Adds dot-density user guide notebook.
docs/source/user-guide/census_to_hexgrid.ipynb	Adds hexgrid user guide notebook.
docs/source/user-guide/binary_dasymetric.ipynb	Adds binary dasymetric user guide notebook.
docs/source/user-guide/01_interpolation_methods_overview.ipynb	Adds interpolation overview user guide notebook.
docs/source/references.md	Adds a references page stub in MyST Markdown.
docs/source/installation.md	Adds installation instructions in Markdown.
docs/source/index.md	Adds new MyST index + toctree structure.
docs/source/conf.py	Introduces new Sphinx configuration (myst-nb, immaterial theme, version switcher, notebook execution settings).
docs/source/api.rst	Adds new API reference page using autosummary.
docs/source/_static/waldo_travel.jpg	Adds an image asset used by docs/theme/content.
docs/source/_static/tobler_long.svg	Adds/updates long logo SVG asset.
docs/source/_static/references.bib	Adds bibliography database for sphinxcontrib-bibtex.
docs/source/_static/pysal_favicon.ico	Adds favicon asset.
docs/source/_static/pysal-styles.css	Adds CSS for layout/styling.
docs/source/Makefile	Adds Sphinx makefile for the new docs/source structure.
docs/references.rst (deleted)	Removes old RST references page.
docs/notebooks/extract_urban_areas.nblink (deleted)	Removes legacy notebook link indirection.
docs/notebooks/census_to_hexgrid.nblink (deleted)	Removes legacy notebook link indirection.
docs/notebooks/binary_dasymetric.nblink (deleted)	Removes legacy notebook link indirection.
docs/notebooks/03_areal_interpolation_details.nblink (deleted)	Removes legacy notebook link indirection.
docs/notebooks/02_areal_interpolation_example.nblink (deleted)	Removes legacy notebook link indirection.
docs/notebooks/01_interpolation_methods_overview.nblink (deleted)	Removes legacy notebook link indirection.
docs/make.bat	Adds Windows Sphinx make script.
docs/installation.rst (deleted)	Removes old RST installation page.
docs/index.rst (deleted)	Removes old RST index page.
docs/conf.py (deleted)	Removes old Sphinx configuration.
docs/apimyst.md (deleted)	Removes old MyST/autodoc2 API draft page.
docs/Makefile	Updates top-level docs makefile to build from docs/source.
README.md	Updates doc asset paths (logo, raster image, NSF logo) to the new static layout.
.gitignore	Ignores new generated/cache paths under docs/source/.
.github/workflows/build_docs.yml	Replaces the docs CI workflow with versioned publishing + PR artifact upload + version switcher update.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[martinfleis]

Nice!

The ReadMe might needs some work if we want to fold it to the index as the relative links no longer works there. If they work in ReadMe, they do not in docs and vice versa.

We'll need to prepare gh-pages branch before merging this. Otherwise the docs action would fail.

The Makefile within source shall be removed.

[knaaptime]

im a bit conflicted about whether notebook optional deps (cenpy, lonboard, etc) should be included in the ci recipe or pip-installed in the notebook itself

[jGaboardi]

im a bit conflicted about whether notebook optional deps (cenpy, lonboard, etc) should be included in the ci recipe or pip-installed in the notebook itself

Why not both? We can put another optional group in the pyproject.toml

[knaaptime]

Why not both? We can put another optional group in the pyproject.toml

I'm not opposed to another pyproject group, but the docs dependencies are installed from conda using the latest ci recipe, so the extra deps need to be maintained there. If something in the user-guide deps broke, we'd probably recognize what happened fairly quickly but it would be better if that just tanked the docs build instead of the unit tests too

[martinfleis]

I would have the required deps defined in the environment to ensure they come from conda but keep the note in the notebook as we have right now.

[martinfleis]

Approving, pending the gh-pages prep.

[martinfleis]

It will also need pysal/libpysal#898

[knaaptime]

im a little confused what i need to do with the gh-pages branch. Do I need to create that folder structure and push manually? The action doesnt create that and push itself?

[martinfleis]

Yes and no. We need to clean current structure and prepare the infra for the version dropdown. I can do that if you want.

[knaaptime]

if you dont mind me watching this first one, then i'll have a handle on what to do for the other packages

[jGaboardi]

if you dont mind me watching this first one, then i'll have a handle on what to do for the other packages

I'll also join "the watching". And if possible let's document the process in pysal/pysal#1432?

[martinfleis]

The way I did this in libpysal is that I essentially manually prepared this https://github.com/pysal/libpysal/tree/gh-pages by directly pushing to the branch. So I built the two versions of the docs, dumped them to right folders (stable and the latest version is a copy of the same) and filled the JSON.

[jGaboardi]

Does the stable alias need to be manually updated each time or is that automatically done?

[martinfleis]

That is automatic. Once you set it up first time, you don't have to touch it.

[jGaboardi]

the docs take forever to execute

@knaaptime , this may be the understatement of the week. ha

[knaaptime]

looks nice!

[jGaboardi]

@knaaptime -- great work on this!