Sphinx documentation

.github/workflows/publish-documentation.yaml

@@ -0,0 +1,45 @@
+name: Publish Documentation
+
+on:
+  workflow_dispatch:
+    inputs:
+      codeflare_sdk_release_version:
+        type: string
+        required: true
+        description: 'Version number (for example: 0.1.0)'
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.9
+      - name: Install Sphinx
+        run: |
+            sudo apt-get update
+            sudo apt-get install python3-sphinx
+      - name: Install Poetry
+        uses: abatilo/actions-poetry@v2
+        with:
+          poetry-version: 1.8.3
+      - name: Create new documentation
+        run: |
+          python3 -m venv .venv
+          source .venv/bin/activate
+          poetry install --with docs
+          sed -i 's/release = "v[0-9]\+\.[0-9]\+\.[0-9]\+"/release = "${{ github.event.inputs.codeflare_sdk_release_version }}"/' docs/sphinx/conf.py
+          sphinx-apidoc -o docs/sphinx src/codeflare_sdk "**/*test_*" --force # Generate docs but ignore test files
+          make html -C docs/sphinx
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/sphinx/_build/html
+          force_orphan: true

.github/workflows/release.yaml

@@ -33,8 +33,6 @@ jobs:
         permissions:
             contents: write
             id-token: write  # This permission is required for trusted publishing
-        env:
-            PR_BRANCH_NAME: adjustments-release-${{ github.event.inputs.release-version }}
         steps:
             - name: Checkout the repository
               uses: actions/checkout@v4
@@ -51,33 +49,17 @@ jobs:
             - name: Run poetry install
               run: poetry install --with docs
             - name: Create new documentation
-              run: poetry run pdoc --html -o docs/detailed-documentation src/codeflare_sdk && pushd docs/detailed-documentation && rm -rf cluster job utils && mv codeflare_sdk/* . && rm -rf codeflare_sdk && popd && find docs/detailed-documentation -type f -name "*.html" -exec bash -c "echo '' >> {}" \;
+              run: |
+                gh workflow run publish-documentation.yaml \
+                  --repo ${{ github.event.inputs.codeflare-repository-organization }}/codeflare-sdk \
+                  --ref ${{ github.ref }} \
+                  --field codeflare_sdk_release_version=${{ github.event.inputs.release-version }}
             - name: Copy demo notebooks into SDK package
               run: cp -r demo-notebooks src/codeflare_sdk/demo-notebooks
             - name: Run poetry build
               run: poetry build
-            - name: Commit changes in docs
-              uses: stefanzweifel/git-auto-commit-action@v4
-              with:
-                file_pattern: 'docs'
-                commit_message: "Changes in docs for release: v${{ github.event.inputs.release-version }}"
-                create_branch: true
-                branch: ${{ env.PR_BRANCH_NAME }}
-            - name: Create a PR with code changes
-              run: |
-                  if git branch -a | grep "${{ env.PR_BRANCH_NAME }}"; then
-                    GIT_BRANCH=${GITHUB_REF#refs/heads/}
-                    gh pr create --base "$GIT_BRANCH" --fill --head "${{ env.PR_BRANCH_NAME }}" --label "lgtm" --label "approved"
-                  fi
               env:
                 GITHUB_TOKEN: ${{ secrets.CODEFLARE_MACHINE_ACCOUNT_TOKEN }}
-            - name: Wait until PR with code changes is merged
-              run: |
-                  if git branch -a | grep "${{ env.PR_BRANCH_NAME }}"; then
-                    timeout 3600 bash -c 'until [[ $(gh pr view '${{ env.PR_BRANCH_NAME }}' --json state --jq .state) == "MERGED" ]]; do sleep 5 && echo "$(gh pr view '${{ env.PR_BRANCH_NAME }}' --json state --jq .state)"; done'
-                  fi
-              env:
-                GITHUB_TOKEN: ${{ github.TOKEN }}
             - name: Create Github release
               uses: ncipollo/release-action@v1
               with:

.gitignore

@@ -13,3 +13,4 @@ node_modules
 ui-tests/playwright-report
 ui-tests/test-results
 /src/codeflare_sdk.egg-info/
+docs/sphinx/_build

README.md

@@ -11,7 +11,7 @@ For guided demos and basics walkthroughs, check out the following links:
 - these demos can be copied into your current working directory when using the `codeflare-sdk` by using the `codeflare_sdk.copy_demo_nbs()` function
 - Additionally, we have a [video walkthrough](https://www.youtube.com/watch?v=U76iIfd9EmE) of these basic demos from June, 2023
 
-Full documentation can be found [here](https://project-codeflare.github.io/codeflare-sdk/detailed-documentation)
+Full documentation can be found [here](https://project-codeflare.github.io/codeflare-sdk/index.html)
 
 ## Installation
 
@@ -32,11 +32,10 @@ It is possible to use the Release Github workflow to do the release. This is gen
 The following instructions apply when doing release manually. This may be required in instances where the automation is failing.
 
 - Check and update the version in "pyproject.toml" file.
-- Generate new documentation.
-`pdoc --html -o docs src/codeflare_sdk && pushd docs && rm -rf cluster job utils && mv codeflare_sdk/* . && rm -rf codeflare_sdk && popd && find docs -type f -name "*.html" -exec bash -c "echo '' >> {}" \;` (it is possible to install **pdoc** using the following command `poetry install --with docs`)
 - Commit all the changes to the repository.
 - Create Github release (<https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release>).
 - Build the Python package. `poetry build`
 - If not present already, add the API token to Poetry.
 `poetry config pypi-token.pypi API_TOKEN`
 - Publish the Python package. `poetry publish`
+- Trigger the [Publish Documentation](https://github.com/project-codeflare/codeflare-sdk/actions/workflows/publish-documentation.yaml) workflow