diff --git a/.github/workflows/doc-build.yaml b/.github/workflows/doc-build.yaml new file mode 100644 index 00000000..f493678f --- /dev/null +++ b/.github/workflows/doc-build.yaml @@ -0,0 +1,77 @@ +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: Setup SSH (Click me for login details) + uses: ./.github/actions/setup-ssh + with: + github-secret: ${{ secrets.GITHUB_TOKEN }} + - 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: Setup SSH (Click me for login details) + uses: ./.github/actions/setup-ssh + with: + github-secret: ${{ secrets.GITHUB_TOKEN }} + - 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 diff --git a/docs/Makefile b/docs/Makefile index dd9632c8..f6720af7 100644 --- a/docs/Makefile +++ b/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 diff --git a/docs/doc_push.sh b/docs/doc_push.sh new file mode 100644 index 00000000..888a8f9d --- /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 +pip install -r dev-requirements.txt +pip install -e . --install-option="--cmakeoff" + +multipy_ver=$(python -c "import multipy; print(multipy.__version__)") + +echo "Building multipy-$multipy_ver docs..." +docs_dir=$repo_root/docs +build_dir=$docs_dir/build +cd "$docs_dir" || exit +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 diff --git a/docs/requirements.txt b/docs/requirements.txt index b6b73d20..33f77426 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -5,4 +5,7 @@ sphinxcontrib.katex matplotlib papermill jinja2<=3.0.3 +breathe exhale +ipython_genutils +ipykernel