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 d900c1d.

* Added linux environment setup

* Made only publish dev when on main and added comments

---------

Co-authored-by: Jonathan McLean <Jonathan.McLean@microsoft.com>

.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 <<EOF
+          from importlib.metadata import version
+          v = version('diskannpy')
+          print(v)
+          EOF
+          )" >> $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 /<version> 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

.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:

.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