DOCS: use nbsphinx-link and include myst beta

.github/workflows/build_docs.yml

@@ -2,47 +2,41 @@
  on:
    push:
      branches:
-     - master
      - main
+
  jobs:
    docs:
-     name: CI (${{ matrix.os }}-${{ matrix.environment-file }})
+     name: Build & Push Docs
      runs-on: ${{ matrix.os }}
-     continue-on-error: ${{ matrix.experimental }}
-     timeout-minutes: 20
+     timeout-minutes: 90
      strategy:
        matrix:
          os: ['ubuntu-latest']
-         environment-file: [ci/311.yml]
+         environment-file: [ci/312.yaml]
          experimental: [false]
      defaults:
        run:
          shell: bash -l {0}
+
      steps:
-       - uses: actions/checkout@v2
-       - uses: actions/cache@v2
-         env:
-           CACHE_NUMBER: 0
+       - name: Checkout repo
+         uses: actions/checkout@v4
          with:
-           path: ~/conda_pkgs_dir
-           key: ${{ matrix.os }}-conda-${{ env.CACHE_NUMBER }}-${{ hashFiles(matrix.environment-file) }}
-       - uses: conda-incubator/setup-miniconda@v2
+           fetch-depth: 0 # Fetch all history for all branches and tags.
+
+       - name: Setup micromamba
+         uses: mamba-org/setup-micromamba@v1
          with:
-            miniconda-version: 'latest'
-            channels: conda-forge
-            channel-priority: true
-            auto-update-conda: true
-            auto-activate-base: false
-            environment-file: ${{ matrix.environment-file }}
-            activate-environment: test
-            use-only-tar-bz2: true
-       - run: conda info --all
-       - run: conda list
-       - run: conda config --show-sources
-       - run: conda config --show
-       - run: pip install -e . --no-deps --force-reinstall
-       - run: cd docs; make html
-       - name: Commit documentation changes
+           environment-file: ${{ matrix.environment-file }}
+           micromamba-version: 'latest'
+
+       - name: Install
+         run: pip install -e . --no-deps --force-reinstall
+
+       - name: Make Docs
+         run: cd docs; make html
+
+       - name: Commit Docs
          run: |
            git clone https://github.com/ammaraskar/sphinx-action-test.git --branch gh-pages --single-branch gh-pages
            cp -r docs/_build/html/* gh-pages/
@@ -51,12 +45,13 @@
            git config --local user.name "GitHub Action"
            git add .
            git commit -m "Update documentation" -a || true
-           # The above command will fail if no changes were present, so we ignore
-           # the return code.
-       - name: Push changes
+           # The above command will fail if no changes were present,
+           # so we ignore the return code.
+
+       - name: Push to gh-pages
          uses: ad-m/github-push-action@master
          with:
             branch: gh-pages
             directory: gh-pages
             github_token: ${{ secrets.GITHUB_TOKEN }}
-            force: true
+            force: true

.github/workflows/unittests.yml

@@ -25,10 +25,10 @@
        matrix:
          os: [ubuntu-latest]
          environment-file: [
-            ci/310.yml,
             ci/311.yml,
             ci/312.yml,
-            ci/312-dev.yml,
+            ci/313.yml,
+            ci/313-dev.yml,
          ]
          include:
            - environment-file: ci/312.yml

.gitignore

@@ -95,3 +95,6 @@ ENV/
 .vscode
 
 nlcd_2011.tif
+
+docs/generated/
+docs/apidocs/

README.md

@@ -3,7 +3,7 @@
 </p>
 
 [![Continuous Integration](https://github.com/pysal/tobler/actions/workflows/unittests.yml/badge.svg)](https://github.com/pysal/tobler/actions/workflows/unittests.yml)
-[![codecov](https://codecov.io/gh/pysal/tobler/branch/master/graph/badge.svg?token=XO4SilfBEb)](https://codecov.io/gh/pysal/tobler)![PyPI - Python Version](https://img.shields.io/pypi/pyversions/tobler)
+[![codecov](https://codecov.io/gh/pysal/tobler/branch/main/graph/badge.svg?token=XO4SilfBEb)](https://codecov.io/gh/pysal/tobler)![PyPI - Python Version](https://img.shields.io/pypi/pyversions/tobler)
 ![PyPI](https://img.shields.io/pypi/v/tobler)
 ![Conda (channel only)](https://img.shields.io/conda/vn/conda-forge/tobler)
 ![GitHub commits since latest release (branch)](https://img.shields.io/github/commits-since/pysal/tobler/latest)
@@ -62,7 +62,7 @@ If you have any suggestion, feature request, or bug report, please open a new [i
 
 ## License
 
-The project is licensed under the [BSD license](https://github.com/pysal/tobler/blob/master/LICENSE.txt).
+The project is licensed under the [BSD license](https://github.com/pysal/tobler/blob/main/LICENSE.txt).
 
 ## Funding
 

ci/311.yml

@@ -29,10 +29,3 @@ dependencies:
   - joblib
   - astropy
   - mapclassify
-  - sphinx>=1.4.3
-  - sphinxcontrib-bibtex==1.0.0
-  - sphinx_bootstrap_theme
-  - numpydoc
-  - nbsphinx
-  - joblib
-  - astropy

ci/312.yml

@@ -23,7 +23,7 @@ dependencies:
   - pytest-cov
   - twine
   - pip
-  - h3-py
+  - h3-py<4
   - mapclassify
   - sphinx>=1.4.3
   - sphinxcontrib-bibtex==1.0.0
@@ -32,3 +32,8 @@ dependencies:
   - nbsphinx
   - joblib
   - astropy
+  - myst-parser
+  - sphinx-autodoc2
+  - nbsphinx-link
+  - pip:
+    - nbsphinx-link>=1.3.1 # not on conda yet

ci/312-dev.yml → ci/313-dev.yml

@@ -2,7 +2,7 @@ name: test
 channels:
   - conda-forge
 dependencies:
-  - python=3.12
+  - python=3.13
   - dask
   - dask-geopandas
   - numpy

ci/310.yml → ci/313.yml

@@ -2,7 +2,7 @@ name: test
 channels:
   - conda-forge
 dependencies:
-  - python=3.10
+  - python=3.13
   - dask
   - dask-geopandas
   - jupyterlab
@@ -25,6 +25,6 @@ dependencies:
   - coverage
   - twine
   - pip
-  - h3-py<4
+  - h3-py
   - joblib
   - astropy

docs/Makefile

@@ -17,7 +17,6 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@rsync -r --exclude '.ipynb_checkpoints/' ../notebooks/ ./notebooks/
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 github:
@@ -33,4 +32,5 @@ clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf auto_examples/
 	rm -rf generated/
+	rm -rf apidocs/