fix up docs

.github/workflows/docs.yml

@@ -42,30 +42,48 @@ jobs:
   docs:
     name: Build documentation
     runs-on: 'ubuntu-22.04'
+    defaults:
+      run:
+        shell: bash -l {0}  # required for conda env
     steps:
       - run: sudo apt install --yes graphviz pandoc
       - uses: actions/checkout@v4
         with:
           ref: ${{ inputs.branch == '' && github.ref_name || inputs.branch }}
           repository: ${{ github.event.pull_request.head.repo.full_name }}
           fetch-depth: 0  # history required so cmake can determine version
-      - uses: actions/setup-python@v5
+      - uses: mamba-org/setup-micromamba@v1
+        if: ${{ inputs.version != '' }}
+        with:
+          environment-file: .buildconfig/ci-linux.yml
+          cache-environment: true
+          create-args: >-
+            python=3.10
+            scippneutron==${{ inputs.version }}
+            tox
+      - uses: mamba-org/setup-micromamba@v1
+        if: ${{ inputs.version == '' }}
         with:
-          python-version-file: '.github/workflows/python-version-ci'
-      - run: python -m pip install --upgrade pip
-      - run: python -m pip install -r requirements/ci.txt
+          environment-file: .buildconfig/ci-linux.yml
+          cache-environment: true
+          create-args: >-
+            python=3.10
+            conda-build
+            tox
+      - run: conda develop src
+        if: ${{ inputs.version == '' }}
       - run: tox -e releasedocs -- ${VERSION}
         if: ${{ inputs.version != '' }}
       - run: tox -e docs
         if: ${{ inputs.version == '' }}
       - run: tox -e linkcheck
         if: ${{ inputs.linkcheck }}
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v3
         with:
           name: docs_html
           path: html/
 
-      - uses: JamesIves/github-pages-deploy-action@v4.6.0
+      - uses: JamesIves/github-pages-deploy-action@v4.4.3
         if: ${{ inputs.publish }}
         with:
           branch: gh-pages

tox.ini

@@ -19,6 +19,28 @@ deps =
   scippneutron[all]
 commands = pytest {posargs}
 
+[testenv:docs]
+description = invoke sphinx-build to build the HTML docs
+deps = -r requirements/docs.txt
+allowlist_externals=find
+commands = python -m sphinx -j2 -v -b html -d {toxworkdir}/docs_doctrees docs html
+           python -m sphinx -j2 -v -b doctest -d {toxworkdir}/docs_doctrees docs html
+           find html -type f -name "*.ipynb" -not -path "html/_sources/*" -delete
+
+[testenv:releasedocs]
+description = invoke sphinx-build to build the HTML docs from a released version
+skip_install = true
+deps =
+  scippneutron=={posargs}
+  {[testenv:docs]deps}
+allowlist_externals={[testenv:docs]allowlist_externals}
+commands = {[testenv:docs]commands}
+
+[testenv:linkcheck]
+description = Run Sphinx linkcheck
+deps = -r requirements/docs.txt
+commands = python -m sphinx -j2 -v -b linkcheck -d {toxworkdir}/docs_doctrees docs html
+
 [testenv:static]
 description = Code formatting and static analysis
 skip_install = true