feat: add docs [SBK-281] (#35)

* chore: upgrade to 3.10 for base * feat: add Python 3.11 supprt * feat: add documentation
ApeWorX · Sep 15, 2023 · 5f8b31d · 5f8b31d
1 parent 7fe10ea
commit 5f8b31d
Show file tree

Hide file tree

Showing 22 changed files with 981 additions and 9 deletions.
diff --git a/.github/workflows/commitlint.yaml b/.github/workflows/commitlint.yaml
@@ -16,7 +16,7 @@ jobs:
         - name: Setup Python
           uses: actions/setup-python@v4
           with:
-              python-version: 3.8
+              python-version: "3.10"
 
         - name: Install Dependencies
           run: pip install commitizen

diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -0,0 +1,57 @@
+name: Docs
+
+on:
+    push:
+        branches: [main]
+    release:
+        types: [released]
+    pull_request:
+        types: [opened, synchronize]
+
+jobs:
+    docs:
+        runs-on: ubuntu-latest
+
+        steps:
+        - uses: actions/checkout@v3
+
+        - name: Setup Python
+          uses: actions/setup-python@v4
+          with:
+              python-version: "3.10"
+
+        - name: Install Dependencies
+          run: |
+            python -m pip install --upgrade pip
+            pip install .[doc]
+
+        - name: Build HTML artifact
+          run: python build_docs.py
+
+        - name: Upload HTML artifact
+          uses: actions/upload-artifact@v3
+          with:
+              name: DocumentationHTML
+              path: docs/_build/silverback
+
+        - name: Commit and publish documentation changes to gh-pages branch
+          run: |
+              if [[ "${GITHUB_EVENT_NAME}" =~ "pull_request" ]]; then
+                echo "skipping 'git commit' step for PR"
+              else
+                git clone https://github.com/${GITHUB_REPOSITORY} --branch gh-pages --single-branch gh-pages
+                cp -r docs/_build/ape/* gh-pages/
+                cd gh-pages
+                touch .nojekyll
+                git config --local user.email "[email protected]"
+                git config --local user.name "GitHub Action"
+                git add .
+                git commit -m "Update documentation" -a || true
+              fi
+        - name: Push changes
+          uses: ad-m/github-push-action@master
+          if: ${{ github.event_name != 'pull_request' }}
+          with:
+              branch: gh-pages
+              directory: gh-pages
+              github_token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml
@@ -15,13 +15,13 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v4
       with:
-        python-version: 3.8
+        python-version: "3.10"
 
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         pip install -e .[release]
-        
+
     - name: Build
       run: python setup.py sdist bdist_wheel
 

diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
@@ -19,7 +19,7 @@ jobs:
         - name: Setup Python
           uses: actions/setup-python@v4
           with:
-              python-version: 3.8
+              python-version: "3.10"
 
         - name: Install Dependencies
           run: |
@@ -47,7 +47,7 @@ jobs:
         - name: Setup Python
           uses: actions/setup-python@v4
           with:
-              python-version: 3.8
+              python-version: "3.10"
 
         - name: Install Dependencies
           run: |
@@ -63,7 +63,7 @@ jobs:
         strategy:
             matrix:
                 os: [ubuntu-latest, macos-latest]   # eventually add `windows-latest`
-                python-version: [3.8, 3.9, "3.10"]
+                python-version: [3.8, 3.9, "3.10", "3.11"]
 
         steps:
         - uses: actions/checkout@v3
@@ -94,7 +94,7 @@ jobs:
 #        - name: Setup Python
 #          uses: actions/setup-python@v4
 #          with:
-#              python-version: 3.8
+#              python-version: "3.10"
 #
 #        - name: Install Dependencies
 #          run: pip install .[test]

diff --git a/build_docs.py b/build_docs.py
@@ -0,0 +1,89 @@
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+REDIRECT_HTML = """
+<!DOCTYPE html>
+<meta charset="utf-8">
+<title>Redirecting...</title>
+<meta http-equiv="refresh" content="0; URL=./{}/">
+"""
+DOCS_BUILD_PATH = Path("docs/_build/silverback")
+LATEST_PATH = DOCS_BUILD_PATH / "latest"
+STABLE_PATH = DOCS_BUILD_PATH / "stable"
+
+
+class ApeDocsBuildError(Exception):
+    pass
+
+
+def git(*args):
+    return subprocess.check_output(["git", *args]).decode("ascii").strip()
+
+
+def new_dir(path: Path) -> Path:
+    if path.exists():
+        shutil.rmtree(path)
+
+    path.mkdir(parents=True)
+    return path
+
+
+def build_docs(path: Path) -> Path:
+    path = new_dir(path)
+
+    try:
+        subprocess.check_call(["sphinx-build", "docs", str(path)])
+    except subprocess.SubprocessError as err:
+        raise ApeDocsBuildError(f"Command 'sphinx-build docs {path}' failed.") from err
+
+    return path
+
+
+def main():
+    """
+    There are three GH events we build for:
+
+    1. Push to main: we build into 'latest/'.
+       The GH action will commit these changes to the 'gh-pages' branch.
+
+    2. Release: we copy 'latest/' into the release dir, as well as to 'stable/'.
+       The GH action will commit these changes to the 'gh-pages' branch.
+
+    3. Pull requests or local development: We ensure a successful build.
+    """
+
+    event_name = os.environ.get("GITHUB_EVENT_NAME")
+    is_ephemeral = event_name in ["pull_request", None]
+
+    if event_name == "push" or is_ephemeral:
+        build_docs(LATEST_PATH)
+    elif event_name == "release":
+        tag = git("describe", "--tag")
+        if not tag:
+            raise ApeDocsBuildError("Unable to find release tag.")
+
+        if "beta" not in tag and "alpha" not in tag:
+            build_dir = DOCS_BUILD_PATH / tag
+            build_docs(build_dir)
+
+            # Clean-up unnecessary extra 'fonts/' directories to save space.
+            # There should still be one in 'latest/'
+            for font_dirs in build_dir.glob("**/fonts"):
+                if font_dirs.exists():
+                    shutil.rmtree(font_dirs)
+
+            shutil.copytree(build_dir, STABLE_PATH)
+        else:
+            build_docs(STABLE_PATH)
+
+    # Set up the redirect at /index.html
+    DOCS_BUILD_PATH.mkdir(exist_ok=True, parents=True)
+    with open(DOCS_BUILD_PATH / "index.html", "w") as f:
+        redirect = "latest" if is_ephemeral else "stable"
+        f.write(REDIRECT_HTML.format(redirect))
+
+
+if __name__ == "__main__":
+    main()