-
Notifications
You must be signed in to change notification settings - Fork 83
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add pdoc integration in GitHub workflows (#207)
## Problem We're working on generating documentation references from the codebase as a part of CI to each client. For Python, we can use [pdoc](https://pdoc.dev/) to generate our client reference as a static webpage which can then be directly deployed to GitHub pages. We also need to update CI workflows to handle building and deploying documentation artifacts. ## Solution - Add `pdoc` as a dependency under `[tool.poetry.group.dev.dependencies]` in `pyproject.toml`. - Add a new `build-docs` action under `.github/actions/`. - Add a `build-docs` job to `pr.yaml` to verify docs build along with testing on prs. - Add new `merge` workflow under `.github/workflows/`. - Update some of the existing docstrings in `index.py` and `manage.py`. **Note:** There's a lot more that needs to be cleaned up with the docstrings and overall formatting of the `pdoc` output. I felt like the PR was getting large so opted to keep this one focused on the CI pieces and getting things properly building in the pipeline. I'll be following up with more fine-grained comment coverage of the top-level modules. I have my default vscode formatter set to black, and I think prettier went a little wild with some of the yaml files. I can try and back out the changes but most of them seem fine to me, although slightly different from some of the styling after black was run the other day. ## Type of Change - [X] New feature (non-breaking change which adds functionality) - [X] Infrastructure change (CI configs, etc) - [X] Non-code change (docs, etc) ## Test Plan Make sure the `Pull Request / Build docs with pdoc` check passes as a part of this PR. I forked the repo and validated the `merge` workflow ran as expected and deployed the docs properly. You can see that run here: https://github.com/austin-denoble/pinecone-python-client/actions/runs/6359304970 You can see the deployed docs in GitHub pages for validation of the overall flow here: https://austin-denoble.github.io/pinecone-python-client/pinecone.html
- v6.0.0.rc2
- v6.0.0.rc1
- v6.0.0.dev6
- v6.0.0.dev5
- v6.0.0.dev4
- v6.0.0.dev3
- v6.0.0.dev2
- v6.0.0.dev1
- v5.4.2
- v5.4.1
- v5.4.0
- v5.4.0.dev5
- v5.4.0.dev4
- v5.4.0.dev3
- v5.4.0.dev2
- v5.4.0.dev1
- v5.3.1
- v5.3.0
- v5.2.0
- v5.2.0.dev10
- v5.2.0.dev9
- v5.2.0.dev8
- v5.2.0.dev7
- v5.2.0.dev6
- v5.2.0.dev5
- v5.2.0.dev4
- v5.2.0.dev3
- v5.2.0.dev2
- v5.2.0.dev1
- v5.2.0.dev0
- v5.1.0
- v5.1.0.rc1
- v5.1.0.dev1
- v5.0.1
- v5.0.0
- v4.1.2
- v4.1.1
- v4.1.0
- v4.0.0
- v3.2.2
- v3.2.1
- v3.2.0
- v3.1.0
- v3.1.0.dev1
- v3.0.3
- v3.0.2
- v3.0.1
- v3.0.0
- v3.0.0.rc3
- v3.0.0.dev10
- v3.0.0.dev9
- v3.0.0.dev8
- v3.0.0.dev7
- v3.0.0.dev6
- v3.0.0.dev5
- v3.0.0.dev4
- v3.0.0.dev3
- v3.0.0.dev2
- v3.0.0.dev1
- v2.3.0.dev1
- v2.2.5.rc2
- v2.2.5.rc1
1 parent
03da225
commit 1b625d8
Showing
13 changed files
with
368 additions
and
153 deletions.
There are no files selected for viewing
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,17 @@ | ||
name: 'Build client documentation' | ||
description: 'Generates client documentation using pdoc' | ||
runs: | ||
using: 'composite' | ||
steps: | ||
- name: Setup Python | ||
uses: actions/setup-python@v4 | ||
with: | ||
python-version: 3.x | ||
|
||
- name: Setup Poetry | ||
uses: ./.github/actions/setup-poetry | ||
|
||
- name: Build html documentation | ||
shell: bash | ||
run: | | ||
poetry run pdoc pinecone/ --favicon ./favicon-32x32.png --docformat google -o ./docs |
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
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,22 @@ | ||
name: 'Merge to main' | ||
|
||
on: | ||
push: | ||
branches: | ||
- main | ||
workflow_dispatch: {} | ||
|
||
jobs: | ||
build-and-deploy-documentation: | ||
runs-on: ubuntu-latest | ||
steps: | ||
- name: Generate pdoc documentation | ||
uses: ./.github/actions/build-docs | ||
|
||
- name: Deploy documentation to gh-pages | ||
uses: s0/git-publish-subdir-action@develop | ||
env: | ||
REPO: self | ||
BRANCH: gh-pages | ||
FOLDER: docs | ||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} |
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,7 +1,21 @@ | ||
name: Pull-request CI | ||
name: Pull Request | ||
|
||
on: pull_request | ||
on: | ||
pull_request: {} | ||
push: | ||
branches: | ||
- main | ||
workflow_dispatch: {} | ||
|
||
jobs: | ||
run-tests: | ||
uses: './.github/workflows/testing.yaml' | ||
uses: './.github/workflows/testing.yaml' | ||
|
||
build-docs: | ||
name: Build docs with pdoc | ||
runs-on: ubuntu-latest | ||
steps: | ||
- name: Checkout | ||
uses: actions/checkout@v3 | ||
- name: Build docs with pdoc | ||
uses: './.github/actions/build-docs' |
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
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
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,2 +1,2 @@ | ||
include LICENSE.txt requirements.txt requirements-grpc.txt pinecone/__version__ pinecone/__environment__ | ||
include LICENSE.txt pinecone/__version__ pinecone/__environment__ | ||
recursive-exclude tests * |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
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
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
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
Large diffs are not rendered by default.
Oops, something went wrong.
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