add docs CI

.github/workflows/docs-build.yaml

@@ -0,0 +1,69 @@
+name: Docs Build
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  docbuild:
+    runs-on: ubuntu-18.04
+    steps:
+      - name: Setup Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+          architecture: x64
+      - name: Checkout MultiPy
+        uses: actions/checkout@v2
+      - name: Install Dependencies
+        run: |
+          set -eux
+          sudo apt-get install -y pandoc doxygen
+          pip install -r docs/requirements.txt
+      - name: Doc Test
+        run: |
+          cd docs
+          make doctest
+      - name: Linkcheck
+        run: |
+          cd docs
+          make linkcheck
+      - name: Doc Build
+        run: |
+          cd docs
+          make html
+
+  docpush:
+    runs-on: ubuntu-18.04
+    needs: docbuild
+    if: ${{ github.ref == 'refs/heads/main' }}
+    steps:
+      - name: Setup Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+          architecture: x64
+      - name: Checkout MultiPy
+        uses: actions/checkout@v2
+      - name: Set Identity
+        run: |
+          set -ex
+          git config --global user.email "[email protected]"
+          git config --global user.name "MultiPy CI Runner"
+      - name: Install Dependencies
+        run: |
+          set -eux
+          sudo apt-get install -y pandoc doxygen
+          pip install -r docs/requirements.txt
+      - name: Build
+        run: |
+          set -ex
+          sudo bash docs/doc_push.sh --dry-run
+      - name: Push
+        run: |
+          set -ex
+          cd /tmp/multipy_docs_tmp/multipy_gh_pages
+          sudo git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
+          git push

docs/doc_push.sh

@@ -0,0 +1,101 @@
+#!/bin/bash
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+#
+# Builds docs from the checkedout HEAD
+# and pushes the artifacts to gh-pages branch in github.com/pytorch/multipy
+#
+# 1. sphinx generated docs are copied to <repo-root>/<version>
+# 2. if a release tag is found on HEAD then redirects are copied to <repo-root>/latest
+# 3. if no release tag is found on HEAD then redirects are copied to <repo-root>/main
+#
+# gh-pages branch should look as follows:
+# <repo-root>
+#           |- 0.1.0rc2
+#           |- 0.1.0rc3
+#           |- <versions...>
+#           |- main (redirects to the most recent ver in trunk, including release)
+#           |- latest (redirects to the most recent release)
+# If the most recent  release is 0.1.0 and main is at 0.1.1rc1 then,
+# https://pytorch.org/multipy/main -> https://pytorch.org/multipy/0.1.1rc1
+# https://pytorch.org/multipy/latest -> https://pytorch.org/multipy/0.1.0
+#
+# Redirects are done via Jekyll redirect-from  plugin. See:
+#   sources/scripts/create_redirect_md.py
+#   Makefile (redirect target)
+#  (on gh-pages branch) _layouts/docs_redirect.html
+
+set -ex
+
+dry_run=0
+for arg in "$@"; do
+    shift
+    case "$arg" in
+        "--dry-run") dry_run=1 ;;
+        "--help") echo "Usage $0 [--dry-run]"; exit 0 ;;
+    esac
+done
+
+repo_origin="$(git remote get-url origin)"
+repo_root=$(git rev-parse --show-toplevel)
+branch=$(git rev-parse --abbrev-ref HEAD)
+commit_id=$(git rev-parse --short HEAD)
+
+if ! release_tag=$(git describe --tags --exact-match HEAD 2>/dev/null); then
+    echo "No release tag found, building docs for main..."
+    redirects=(main)
+    release_tag="main"
+else
+    echo "Release tag $release_tag found, building docs for release..."
+    redirects=(latest main)
+fi
+
+echo "Installing multipy from $repo_root..."
+cd "$repo_root" || exit
+
+# Not sure why this is on python 2, but if we are only
+# printing out variables, it should be fine. Let's change
+# it if we are doing something more complicated.
+ multipy_ver=$(python -c "from multipy.version import __version__; print __version__")
+
+echo "Building multipy-$multipy_ver docs..."
+docs_dir=$repo_root/docs
+build_dir=$docs_dir/build
+cd "$docs_dir" || exit
+python3 -m pip install setuptools
+python3 -m pip install -r requirements.txt
+make clean html
+echo "Doc build complete"
+
+tmp_dir=/tmp/multipy_docs_tmp
+rm -rf "${tmp_dir:?}"
+
+echo "Checking out gh-pages branch..."
+gh_pages_dir="$tmp_dir/multipy_gh_pages"
+git clone -b gh-pages --single-branch "$repo_origin"  $gh_pages_dir
+
+echo "Copying doc pages for $multipy_ver into $gh_pages_dir..."
+rm -rf "${gh_pages_dir:?}/${multipy_ver:?}"
+cp -R "$build_dir/html" "$gh_pages_dir/$multipy_ver"
+
+cd $gh_pages_dir || exit
+
+for redirect in "${redirects[@]}"; do
+  echo "Creating redirect symlinks for: $redirect -> $multipy_ver..."
+  rm -rf "${gh_pages_dir:?}/${redirect:?}"
+  ln -s "$multipy_ver" "$redirect"
+done
+
+git add .
+git commit --quiet -m "[doc_push][$release_tag] built from $commit_id ($branch). Redirects: ${redirects[*]} -> $multipy_ver."
+
+if [ $dry_run -eq 1 ]; then
+    echo "*** --dry-run mode, skipping push to gh-pages branch. To publish run: cd ${gh_pages_dir} && git push"
+    exit
+fi
+
+git push

docs/requirements.txt

@@ -1,9 +1,12 @@
-sphinx==5.0.1
+sphinx
 sphinx-autobuild
 -e git+http://github.com/pytorch/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme
 sphinx-gallery<=0.7.0
 sphinxcontrib.katex
 matplotlib
 papermill
 jinja2<=3.0.3
+breathe
 exhale
+ipython_genutils
+ipykernel