diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 922a6dd53c..aa0d674d1b 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -1,72 +1,34 @@ name: Docs on: - push: - branches: [main] - release: - types: [released] - pull_request: - types: [opened, synchronize] + push: + branches: [main] + release: + types: [released] + pull_request: + types: [opened, synchronize] jobs: - docs: - runs-on: ubuntu-latest + docs: + runs-on: ubuntu-latest - permissions: - contents: write + permissions: + contents: write - steps: - - uses: actions/checkout@v4 + steps: + - uses: actions/checkout@v4 - - name: Setup Python - uses: actions/setup-python@v5 - with: - python-version: "3.10" + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: "3.10" - - name: Install Dependencies - run: | - python -m pip install --upgrade pip - pip install .[doc] + - 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@v4 - with: - name: DocumentationHTML - path: docs/_build/ape - - - name: Doctesting - run: | - sphinx-build -b doctest docs docs/_build/doctest - if grep -q '0 failed' docs/_build/doctest/output.txt; then - echo "All doctests passed!" - else - echo "Some doctests failed. See the output below." - cat docs/_build/doctest/output.txt - exit 1 - fi - - - 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 "action@github.com" - 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 }} - + - name: Ape Docs + uses: apeworx/sphinx-ape@main + with: + github-token: ${{ secrets.GITHUB_TOKEN }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9d6d9c7f32..27402e9cc0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -58,19 +58,21 @@ pip install -e .'[doc]' Then, run the following from the root project directory: ```bash -python build_docs.py +sphinx-ape build . ``` For the best viewing experience, use a local server: ```bash -python -m http.server --directory "docs/_build/" --bind 127.0.0.1 1337 +sphinx-ape serve . ``` Then, open your browser to `127.0.0.1:1337` and click the `ape` directory link. -```{note} -Serving from `"docs/_build/"` rather than `"docs/_build/ape"` is necessary to make routing work. +You can also use the `--open` flag to automatically open the docs: + +```bash +sphinx-ape serve . --open ``` ## Pull Requests diff --git a/build_docs.py b/build_docs.py deleted file mode 100644 index 870d477a30..0000000000 --- a/build_docs.py +++ /dev/null @@ -1,90 +0,0 @@ -import os -import shutil -import subprocess -from pathlib import Path - -REDIRECT_HTML = """ - - -