add docs CI

ghstack-source-id: 8f2df50bd58b93818ea75ced4a6bf9b5c4f26fcb
Pull Request resolved: #232

mend

.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
+          git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
+          git push

.github/workflows/docs.yaml

@@ -0,0 +1,63 @@
+# This workflow builds the multipy docs and deploys them to gh-pages.
+# It is very heavily inspired by torchrec's script to deploy to gh-pages.
+name: Generate documentation
+on:
+  push:
+    branches:
+      - main
+  # pull_request:
+jobs:
+  build_docs_job:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        include:
+         - os: linux.2xlarge
+           python-version: 3.8
+    steps:
+    - name: Check ldd --version
+      run: ldd --version
+    - name: Checkout
+      uses: actions/checkout@v2
+    - name: Setup SSH (Click me for login details)
+      uses: ./.github/actions/setup-ssh
+      with:
+        github-secret: ${{ secrets.GITHUB_TOKEN }}
+    # Update references
+    - name: Update pip
+      run: |
+        sudo yum update -y
+        sudo yum -y install git python3-pip doxygen
+        sudo pip3 install --upgrade pip
+    - name: Setup conda
+      run: |
+        wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda.sh
+        bash ~/miniconda.sh -b -p $HOME/miniconda
+    - name: setup Path
+      run: |
+        echo "/home/ec2-user/miniconda/bin" >> $GITHUB_PATH
+        echo "CONDA=/home/ec2-user/miniconda" >> $GITHUB_PATH
+    - name: create conda env
+      run: |
+        conda create --name build_binary python=${{ matrix.python-version }}
+        conda info
+    - name: check python version no Conda
+      run: |
+        python --version
+    - name: check python version
+      run: |
+        conda run -n build_binary python --version
+    - name: Build the docset
+      run: |
+        conda run -n build_binary python -m pip install -r docs/requirements.txt
+        cd docs
+        conda run -n build_binary make html
+        cd ..
+    - name: Get output time
+      run: echo "The time was ${{ steps.build.outputs.time }}"
+    - name: Deploy
+      uses: JamesIves/github-pages-deploy-action@releases/v3
+      with:
+          ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH: gh-pages # The branch the action should deploy to.
+          FOLDER: docs/build/html # The folder the action should deploy.

docs/Makefile

@@ -14,6 +14,11 @@ help:
 
 .PHONY: help Makefile
 
+clean:
+	@echo "Deleting build directory"
+	rm -rf "$(BUILDDIR)"
+	rm -rf _doxygen/ api/
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

docs/doc_push.sh

@@ -0,0 +1,100 @@
+#!/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
+
+multipy_ver="0.1.0dev0"
+
+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/$multipy_ver/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
+
+"$docs_dir"/versions_html.py
+
+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,8 +1,12 @@
-sphinx==5.0.1
--e git+http://github.com/pytorch/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme
+sphinx
+# PyTorch Theme
+-e git+https://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