This is an automated email from the ASF dual-hosted git repository. skrawcz pushed a commit to branch stefan/docs in repository https://gitbox.apache.org/repos/asf/burr.git
commit 0790fab6ee15c738bf65c57d8a49d5c61ded87cd Author: Stefan Krawczyk <[email protected]> AuthorDate: Sun Sep 7 22:35:52 2025 -0700 Adds github and asf workflow for docs To publish docs we need to publish via the ASF preferred mechanism. This hopefully sets things up. --- .asf.yaml | 8 +++ .github/workflows/sphinx-docs.yml | 139 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 147 insertions(+) diff --git a/.asf.yaml b/.asf.yaml index 4b3ef789..79a8bdde 100644 --- a/.asf.yaml +++ b/.asf.yaml @@ -58,3 +58,11 @@ notifications: pullrequests: [email protected] discussions: [email protected] jobs: [email protected] + + +staging: + profile: ~ + whoami: asf-staging + +publish: + whoami: asf-site diff --git a/.github/workflows/sphinx-docs.yml b/.github/workflows/sphinx-docs.yml new file mode 100644 index 00000000..496d206c --- /dev/null +++ b/.github/workflows/sphinx-docs.yml @@ -0,0 +1,139 @@ +name: Build Sphinx Documentation + +on: + push: + branches: [ "main", "update_references"] + paths: + - 'docs/**' + - '.github/workflows/sphinx-docs.yml' + pull_request: + branches: [ "main", "update_references" ] + paths: + - 'docs/**' + - '.github/workflows/sphinx-docs.yml' + workflow_dispatch: + +concurrency: + group: "doc-pages" + cancel-in-progress: true + +jobs: + build-docs: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Set up Python 3.12 + uses: actions/setup-python@v5 + with: + python-version: '3.12' + cache: 'pip' + + - name: Install system dependencies + run: | + sudo apt-get update + sudo apt-get install -y graphviz + + - name: Upgrade pip and setuptools + run: | + python -m pip install --upgrade --no-cache-dir pip setuptools + + - name: Install Sphinx and dependencies + run: | + python -m pip install --upgrade --no-cache-dir sphinx sphinx-rtd-theme sphinx-simplepdf + # python -m pip install --group documentation --upgrade --upgrade-strategy only-if-needed --no-cache-dir + pip install -e ".[documentation]" + + - name: Build Sphinx documentation + working-directory: ./docs + run: | + # sphinx-build docs -b dirhtml _build + python -m sphinx -T -W --keep-going -b dirhtml -d _build/doctrees -D language=en . _build/html + + - name: Upload HTML artifact + uses: actions/upload-artifact@v4 + with: + name: sphinx-docs-html + path: docs/_build/html/ + retention-days: 5 + + - name: Upload PDF artifact + uses: actions/upload-artifact@v4 + with: + name: sphinx-docs-pdf + path: docs/_build/pdf/ + retention-days: 5 + + - name: Deploy documentation + working-directory: ./docs + run: | + # Set target branch based on current branch + if [ "${{ github.ref }}" = "refs/heads/main" ]; then + TARGET_BRANCH="asf-site" + echo "Deploying to production (asf-site) branch" + else + TARGET_BRANCH="asf-staging" + echo "Deploying to staging (asf-staging) branch" + fi + + # Configure git + git config --global user.name "GitHub Actions" + git config --global user.email "[email protected]" + + # Create a temporary directory + mkdir -p /tmp/gh-pages + + # Store current directory + CURRENT_DIR=$(pwd) + ls -lsa $CURRENT_DIR + + # Try to clone the repository with the target branch + if ! git clone --branch $TARGET_BRANCH --single-branch \ + https://github.com/${{ github.repository }}.git /tmp/gh-pages 2>/dev/null; then + # If branch doesn't exist, initialize a new repository and create the branch + echo "Branch $TARGET_BRANCH doesn't exist. Creating it..." + rm -rf /tmp/gh-pages + mkdir -p /tmp/gh-pages + cd /tmp/gh-pages + git init + git config --local init.defaultBranch $TARGET_BRANCH + git checkout -b $TARGET_BRANCH + git remote add origin https://github.com/${{ github.repository }}.git + cd "$CURRENT_DIR" + else + echo "CD'ing into $CURRENT_DIR" + cd "$CURRENT_DIR" + fi + + # Remove existing content directory if it exists + rm -rf /tmp/gh-pages/content + + # # Ensure build directories exist + # mkdir -p "$CURRENT_DIR/_build/html" + + # Copy the built HTML documentation to the content directory + mkdir -p /tmp/gh-pages/content + cp -r "$CURRENT_DIR/_build/html/"* /tmp/gh-pages/content/ 2>/dev/null || echo "No HTML files to copy" + + # Add, commit and push the changes + cd /tmp/gh-pages + git status + ls -lhsa content + # Create a README if it doesn't exist + if [ ! -f README.md ]; then + echo "# Documentation for $TARGET_BRANCH" > README.md + echo "This branch contains the built documentation." >> README.md + fi + git add -A + git status + # Check if there are changes to commit (including untracked files) + if [ -n "$(git status --porcelain)" ]; then + git commit -m "Deploy documentation from ${{ github.sha }}" + git push https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.git $TARGET_BRANCH + echo "Changes pushed to $TARGET_BRANCH branch" + else + echo "No changes to deploy" + fi
