From 67bc75e72220e717c706b8d28f3fc24c32e04f49 Mon Sep 17 00:00:00 2001 From: Sahan Paliskara Date: Wed, 26 Oct 2022 16:39:50 -0700 Subject: [PATCH] add docs CI ghstack-source-id: f95e303cd92a22c4230df3551605415b13079790 Pull Request resolved: https://github.com/pytorch/multipy/pull/232 mend --- .github/workflows/docs-build.yaml | 69 ++++++++++++++++++++++ .github/workflows/docs.yaml | 63 ++++++++++++++++++++ docs/Makefile | 5 ++ docs/doc_push.sh | 98 +++++++++++++++++++++++++++++++ docs/requirements.txt | 8 ++- 5 files changed, 241 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/docs-build.yaml create mode 100644 .github/workflows/docs.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..ee9bcde4 --- /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/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 00000000..6a2a147b --- /dev/null +++ b/.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. 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..0df27f91 --- /dev/null +++ b/docs/doc_push.sh @@ -0,0 +1,98 @@ +#!/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 + +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/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 b6b73d20..fb28e8a6 100644 --- a/docs/requirements.txt +++ b/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