Docs #30
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # Builds and deploys the python documentation using sphinx. Live documentation | |
| # is available from the main Astro Data Lab website. | |
| name: Deploy Documentation | |
| env: | |
| # these are defaults in case these values do not get set at runtime | |
| PACKAGE_VERSION: latest | |
| RELEASE_NAME: latest | |
| EXCLUDE_PATTERNS: ../../dl/specClient.py | |
| on: | |
| workflow_dispatch: | |
| inputs: | |
| packageVersion: | |
| description: 'Package Version' | |
| required: true | |
| type: string | |
| commitSha: | |
| description: 'Commit SHA' | |
| required: true | |
| type: string | |
| release: | |
| types: [released] | |
| jobs: | |
| deploy-docs-html: | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 5 | |
| steps: | |
| - uses: actions/checkout@v4 | |
| # This step is here so that when running the workflow manually we can switch | |
| # to some specific ref that may not have a matching tag. We can rebuild the docs | |
| # with some commit and a version label eg. commitSha: 934812 packageVersion: 2.23.1 | |
| # and the version doesn't have to match an existing tag. | |
| - name: Changing commit to (defaults to event ref) ${{ github.event.inputs.commitSha }} | |
| run: | | |
| if [[ ! -z "${{ github.event.inputs.commitSha }}" ]]; then | |
| git checkout ${{ github.event.inputs.commitSha }} | |
| else | |
| echo "Already on default ref" | |
| fi | |
| # Here we either set the package version to the user provided input or the | |
| # tag. This way we can handle both a release trigger and manual trigger | |
| - name: Set package version | |
| run: | | |
| if [[ ! -z "${{ github.event.inputs.packageVersion }}" ]]; then | |
| echo PACKAGE_VERSION="${{ github.event.inputs.packageVersion }}" >> $GITHUB_ENV | |
| elif [[ "${{ github.ref_type }}" == "tag" ]]; then | |
| echo PACKAGE_VERSION="${{ github.ref_name }}" >> $GITHUB_ENV | |
| fi | |
| # We need to set some release name for our sphinx build, for now we keep it | |
| # the same as whatever the package version is | |
| - name: Set release name | |
| run: echo RELEASE_NAME="${{ env.PACKAGE_VERSION }}" >> $GITHUB_ENV | |
| # Install the deps and build the sphinx project | |
| - name: Install job dependencies | |
| run: pip install Sphinx==7.3.7 | |
| - name: Install astro-datalab dependencies | |
| run: pip install . | |
| - name: Create sphinx project | |
| working-directory: docs/sphinx | |
| run: | | |
| PACKAGE_VERSION=${{ env.PACKAGE_VERSION }} \ | |
| RELEASE_NAME=${{ env.RELEASE_NAME }} \ | |
| sphinx-apidoc -f -M -F -e \ | |
| --implicit-namespaces \ | |
| -d 3 \ | |
| -o ./_sphinx/ \ | |
| ../../dl/ \ | |
| "${{ env.EXCLUDE_PATTERNS }}" | |
| # We need to tweak some things in the rst files and then run the html build. | |
| # Overwrite the conf.py file with the one from our repo and also replace any | |
| # instances of the text "dl's" with "astro-datalab's" (sphinx outputs the | |
| # name as "dl" and there is no config option for it) | |
| - name: Sync config file | |
| working-directory: docs/sphinx | |
| run: cp conf.py _sphinx/conf.py | |
| - name: Replace default text "dl's" with "astro-datalab's" in index.rst (toc) | |
| run: sed -i "s/dl's/astro-datalab's/g" docs/sphinx/_sphinx/index.rst | |
| - name: Generate html | |
| working-directory: docs/sphinx/_sphinx | |
| run: make html && ls _build/html | |
| # If we made it to this point we can upload the artifact and register the | |
| # artifact ID | |
| - uses: actions/upload-artifact@v4 | |
| id: upload-html | |
| with: | |
| name: api-docs-html-${{ env.PACKAGE_VERSION }} | |
| path: docs/sphinx/_sphinx/_build/html/ | |
| retention-days: 1 | |
| overwrite: true | |
| - name: Set artifact id | |
| run: echo ARTIFACT_ID="${{ steps.upload-html.outputs.artifact-id }}" >> $GITHUB_ENV | |
| # Prepare our hook data and send "deploy-docs" event | |
| - name: Set payload data | |
| run: echo HOOK_DATA='{"repository":{"name":"datalab"},"event":"deploy-docs","artifact_id":"${{ env.ARTIFACT_ID }}"}' >> $GITHUB_ENV | |
| - name: Generate signature | |
| run: | | |
| SIG=$(echo -n '${{ env.HOOK_DATA }}' | openssl dgst -sha256 -hmac "${{ secrets.APIDOCS_DEPLOY_KEY }}" -hex | sed s/.*\(stdin\)//g | sed s/=//g ) | |
| echo "::add-mask::$SIG" | |
| echo SIG=$SIG >> $GITHUB_ENV | |
| - name: Dispatch hook | |
| run: | | |
| curl --fail \ | |
| -d '${{ env.HOOK_DATA }}' \ | |
| -H "X-Hub-Signature-256: ${{ env.SIG }}" \ | |
| "${{ secrets.APIDOCS_HOOK_URL }}" |