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.
Description of changes: This PR adds a Github Actions workflow that generates documentation for
fmevalin the form of html files via pdoc. These html files are then used by thefmevalrepo's Github Pages site.Note that using
pdocis nothing new; we already usedpdocto generate library documentation in the past (see the docs branch of this repo). Currently, thefmevalrepo is configured to update the Github Pages site whenever a new commit is made to thedocsbranch. This isn't ideal, since it means that for virtually every commit, we have to manually checkout thedocsbranch, runpdocto generate the updated documentation, then push the changes to the remotedocsbranch. 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
mainwill 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
ymlfile 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.