docs: create Github Actions workflow for generating docs via pdoc #260
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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 thefmeval
repo's Github Pages site.Note that using
pdoc
is nothing new; we already usedpdoc
to generate library documentation in the past (see the docs branch of this repo). Currently, thefmeval
repo is configured to update the Github Pages site whenever a new commit is made to thedocs
branch. This isn't ideal, since it means that for virtually every commit, we have to manually checkout thedocs
branch, runpdoc
to generate the updated documentation, then push the changes to the remotedocs
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 onpdoc
'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.