Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: create Github Actions workflow for generating docs via pdoc #260

Merged
merged 1 commit into from
Apr 23, 2024

Conversation

danielezhu
Copy link
Contributor

@danielezhu danielezhu commented Apr 23, 2024

Description of changes:
This PR adds a Github Actions workflow that generates documentation for fmeval in the form of html files via pdoc. These html files are then used by the fmeval repo's Github Pages site.

Note that using pdoc is nothing new; we already used pdoc to generate library documentation in the past (see the docs branch of this repo). Currently, the fmeval repo is configured to update the Github Pages site whenever a new commit is made to the docs branch. This isn't ideal, since it means that for virtually every commit, we have to manually checkout the docs branch, run pdoc to generate the updated documentation, then push the changes to the remote docs branch. Notice how we have not done this in 4 months.

By setting up this Github Actions workflow, the entire process of updating the Github Pages site is fully automated, meaning that no additional effort has to be made. Every PR that gets merged into main will update the Github Pages site automatically.

I have tested this workflow on my own fork. You can see the successful action results here. The workflow yml file is based on pdoc's own workflow file.

Note: unlike the "Lint Checks" and "Unit Test coverage" workflows, I don't want this workflow to run every time a PR is submitted, since the workflow also includes the step of publishing the updated website. We only want the updates to get published when the PR gets merged (otherwise, if there a PR has multiple revisions which affect the documentation as well, there will be windows of time where the documentation contains WIP changes, which ideally shouldn't get exposed to the public).

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Copy link
Member

@keerthanvasist keerthanvasist left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for working on this!

@danielezhu danielezhu merged commit 794f0e0 into aws:main Apr 23, 2024
2 of 3 checks passed
@danielezhu danielezhu deleted the pdoc branch April 23, 2024 22:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants