From 116ca46ac6d1e9453748951f6cd65b07086ec623 Mon Sep 17 00:00:00 2001 From: Sahan Paliskara Date: Fri, 28 Oct 2022 17:11:15 -0700 Subject: [PATCH] add docs CI ghstack-source-id: 7bf4f24bbcba09f55d225df980d4fb2fcef9a3ac Pull Request resolved: https://github.com/pytorch/multipy/pull/232 mend --- .github/workflows/docs-build.yaml | 69 ++++++++++++++++++++ docs/doc_push.sh | 101 ++++++++++++++++++++++++++++++ docs/requirements.txt | 5 +- 3 files changed, 174 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/docs-build.yaml create mode 100644 docs/doc_push.sh diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml new file mode 100644 index 00000000..4e5cfab0 --- /dev/null +++ b/.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 "runner@github.com" + 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 diff --git a/docs/doc_push.sh b/docs/doc_push.sh new file mode 100644 index 00000000..cedea56f --- /dev/null +++ b/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 / +# 2. if a release tag is found on HEAD then redirects are copied to /latest +# 3. if no release tag is found on HEAD then redirects are copied to /main +# +# gh-pages branch should look as follows: +# +# |- 0.1.0rc2 +# |- 0.1.0rc3 +# |- +# |- 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 diff --git a/docs/requirements.txt b/docs/requirements.txt index c268900c..f7040316 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,4 @@ -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 @@ -6,4 +6,7 @@ sphinxcontrib.katex matplotlib papermill jinja2<=3.0.3 +breathe exhale +ipython_genutils +ipykernel