Test docs on PR; deploy docs on push to default branch

.github/workflows/docs.yml

@@ -0,0 +1,35 @@
+name: Build docs
+on:
+  pull_request:
+  workflow_call:
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+
+      - name: Setup Graphviz
+        run: |
+          sudo apt install graphviz -y
+
+      - name: Install versioned-hdf5
+        run: |
+          pip install .[doc]
+
+      - name: Build docs
+        working-directory: docs
+        run: |
+          # Need to set timezone to avoid a sphinx/babel issue
+          # when using act to run locally:
+          # https://github.com/nektos/act/issues/1853
+          TZ=UTC make html
+
+      - name: Upload docs
+        uses: actions/upload-artifact@v3
+        with:
+          name: docs
+          path: docs/_build/html/*

.github/workflows/publish_docs.yml

@@ -0,0 +1,47 @@
+name: Deploy static content to Pages
+
+on:
+  push:
+    branches: ["master"]
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    uses: deshaw/versioned-hdf5/.github/workflows/docs.yml@master
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Download docs
+        uses: actions/download-artifact@v3
+        with:
+          name: docs
+          path: docs
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: 'docs/'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

docs/conf.py

@@ -34,6 +34,7 @@
     'myst_parser',
     'sphinx.ext.autodoc',
     'sphinx.ext.graphviz',
+    'sphinx.ext.intersphinx',
 ]
 
 graphviz_output_format = 'svg'
@@ -46,6 +47,14 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+autodoc_type_aliases = {
+    "File": "h5py.File"
+}
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'h5py': ('https://docs.h5py.org/en/stable', None)
+}
 
 # -- Options for HTML output -------------------------------------------------
 

rever.xsh

@@ -35,15 +35,9 @@ $ACTIVITIES = [
             'push_tag',  # Pushes the tag up to the $TAG_REMOTE
             # 'ghrelease',  # Creates a Github release entry for the new tag
             'pypi',  # Sends the package to pypi
-            # 'ghpages',
 ]
 
 $PUSH_TAG_REMOTE = '[email protected]:deshaw/versioned-hdf5.git'  # Repo to push tags to
 
 $GITHUB_ORG = 'deshaw'  # Github org for Github releases and conda-forge
 $GITHUB_REPO = 'versioned-hdf5'  # Github repo for Github releases and conda-forge
-
-$GHPAGES_REPO = '[email protected]:deshaw/versioned-hdf5.git'
-$GHPAGES_COPY = $GHPAGES_COPY = (
-    ('docs/_build/html', '$GHPAGES_REPO_DIR'),
-)

setup.py

@@ -30,6 +30,10 @@
     extras_require={
         "test": [
             "pytest",
+        ],
+        "doc": [
+            "sphinx",
+            "myst-parser",
         ]
     }
 )

versioned_hdf5/replay.py

@@ -480,7 +480,6 @@ def _walk(g: HLObject, prefix: str = '') -> List[str]:
 
     return datasets
 
-
 def delete_versions(
     f: Union[VersionedHDF5File, File],
     versions_to_delete: Iterable[str]