From 3f58b99777e6f462c4f487fe5c24b6288eb55436 Mon Sep 17 00:00:00 2001 From: Jon McLean <4429525+jonmclean@users.noreply.github.com> Date: Fri, 4 Aug 2023 09:21:57 -0700 Subject: [PATCH] Added PDoc workflow to publish github pages documentation (#412) * Added PDoc workflow * Added documentation to the push-test workflow * Added diskannpy to the env for pdoc to use * Initial commit of doc publish workflow * Tried heredoc to get python version * Tried another way of getting the version * Tried another way of getting the version * Moved to docs/python path * Removing the test harness * Add dependencies per wheel * Moved dependency tree to the 'push' file so it runs on push * Added label name to the dependency file * Trying maxtrix.os to get the os and version * Moved doc generation from push-test to python-release. Will add 'dev' doc generation to push-test * Publish latest/version docs only on release. Publish docs for every dev build on main. * Install the local-file version of the library * Disable branch check so I can test the install * Use python build to build a wheel for use in documentation * Tried changing to python instead of python3 * Added checkout depth in order to get boost * Use the python build action to create wheel for documentation * Revert "Use the python build action to create wheel for documentation" This reverts commit d900c1d42c0f4bc8295955e0d6da7a868a073661. * Added linux environment setup * Made only publish dev when on main and added comments --------- Co-authored-by: Jonathan McLean --- .github/workflows/build-python-pdoc.yml | 78 +++++++++++++++++++++++++ .github/workflows/push-test.yml | 16 +++++ .github/workflows/python-release.yml | 5 ++ 3 files changed, 99 insertions(+) create mode 100644 .github/workflows/build-python-pdoc.yml diff --git a/.github/workflows/build-python-pdoc.yml b/.github/workflows/build-python-pdoc.yml new file mode 100644 index 000000000..c9f4c6494 --- /dev/null +++ b/.github/workflows/build-python-pdoc.yml @@ -0,0 +1,78 @@ +name: DiskANN Build PDoc Documentation +on: [workflow_call] +jobs: + build-reference-documentation: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v3 + with: + fetch-depth: 1 + - name: Set up Python 3.9 + uses: actions/setup-python@v2 + with: + python-version: 3.9 + - name: Install python build + run: python -m pip install build + shell: bash + # Install required dependencies + - name: Prepare Linux environment + run: | + sudo scripts/dev/install-dev-deps-ubuntu.bash + shell: bash + # We need to build the wheel in order to run pdoc. pdoc does not seem to work if you just point it at + # our source directory. + - name: Building Python Wheel for documentation generation + run: python -m build --wheel --outdir documentation_dist + shell: bash + - name: "Run Reference Documentation Generation" + run: | + pip install pdoc pipdeptree + pip install documentation_dist/*.whl + echo "documentation" > dependencies_documentation.txt + pipdeptree >> dependencies_documentation.txt + pdoc -o docs/python/html diskannpy + - name: Create version environment variable + run: | + echo "DISKANN_VERSION=$(python <> $GITHUB_ENV + - name: Archive documentation version artifact + uses: actions/upload-artifact@v2 + with: + name: dependencies + path: | + dependencies_documentation.txt + - name: Archive documentation artifacts + uses: actions/upload-artifact@v2 + with: + name: documentation-site + path: | + docs/python/html + # Publish to /dev if we are on the "main" branch + - name: Publish reference docs for latest development version (main branch) + uses: peaceiris/actions-gh-pages@v3 + if: github.ref == 'refs/heads/main' + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: docs/python/html + destination_dir: docs/python/dev + # Publish to / if we are on the "main" branch and releasing + - name: Publish reference docs by version (main branch) + uses: peaceiris/actions-gh-pages@v3 + if: github.event_name == 'release' && github.ref == 'refs/heads/main' + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: docs/python/html + destination_dir: docs/python/${{ env.DISKANN_VERSION }} + # Publish to /latest if we are on the "main" branch and releasing + - name: Publish latest reference docs (main branch) + uses: peaceiris/actions-gh-pages@v3 + if: github.event_name == 'release' && github.ref == 'refs/heads/main' + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: docs/python/html + destination_dir: docs/python/latest \ No newline at end of file diff --git a/.github/workflows/push-test.yml b/.github/workflows/push-test.yml index 4de999014..23403c0c2 100644 --- a/.github/workflows/push-test.yml +++ b/.github/workflows/push-test.yml @@ -6,6 +6,11 @@ jobs: fail-fast: true name: DiskANN Common Build Checks uses: ./.github/workflows/common.yml + build-documentation: + strategy: + fail-fast: true + name: DiskANN Build Documentation + uses: ./.github/workflows/build-python-pdoc.yml build: strategy: fail-fast: false @@ -28,6 +33,17 @@ jobs: with: fetch-depth: 1 submodules: true + - name: Build dispannpy dependency tree + run: | + pip install diskannpy pipdeptree + echo "dependencies" > dependencies_${{ matrix.os }}.txt + pipdeptree >> dependencies_${{ matrix.os }}.txt + - name: Archive dispannpy dependencies artifact + uses: actions/upload-artifact@v3 + with: + name: dependencies + path: | + dependencies_${{ matrix.os }}.txt - name: DiskANN Build CLI Applications uses: ./.github/actions/build # python: diff --git a/.github/workflows/python-release.yml b/.github/workflows/python-release.yml index a1e72ad90..a0414f13b 100644 --- a/.github/workflows/python-release.yml +++ b/.github/workflows/python-release.yml @@ -6,6 +6,11 @@ jobs: python-release-wheels: name: Python uses: ./.github/workflows/build-python.yml + build-documentation: + strategy: + fail-fast: true + name: DiskANN Build Documentation + uses: ./.github/workflows/build-python-pdoc.yml release: runs-on: ubuntu-latest needs: python-release-wheels