Generate api docs for EESSI test suite #319
Conversation
|
@casparvl Adjusted the deploy and schedule. This is ready for test |
warning message: The following actions use a deprecated Node.js version and will be forced to run on node20: actions/checkout@93ea575, actions/setup-python@13ae5bb. For more info: https://github.blog/changelog/2024-03-07-github-actions-all-actions-will-run-on-node20-instead-of-node16-by-default/
|
Just to log for myself: to test this, one needs to
|
| @@ -57,6 +56,7 @@ nav: | |||
| - Release notes: test-suite/release-notes.md | |||
| - Known issues and workarounds: | |||
| - v2023.06: known_issues/eessi-2023.06.md | |||
| - API documentation: api/ | |||
There was a problem hiding this comment.
I would put this under Advanced usage => Test suite. I'm not sure if we should keep the test suite docs there indefinitely, might be better to have a separate test suite top level item. But that's of later concern. At least we should keep all the test suite stuff under the Test suite: list.
There was a problem hiding this comment.
Probably put it at the bottom of all the other items, i.e. right under - Release notes:
| uses: actions/checkout@v4 | ||
| with: | ||
| repository: eessi/test-suite | ||
| path: src |
There was a problem hiding this comment.
Why don't we just do this without path, i.e. in the current workdir? It will still clone into a subidr test-suite by default right? No need to nest that further inside a src I'd think.
| # need to adjust to the test suite hook | ||
| #root = Path(__file__).parent.parent | ||
|
|
||
| TEST_SUITE = "src/test-suite" |
There was a problem hiding this comment.
Same here, this would then just be `"test-suite"
|
|
||
| import mkdocs_gen_files | ||
|
|
||
| # need to adjust to the test suite hook |
There was a problem hiding this comment.
There seem to be quite some comments that are no longer relevant in this gen_ref_pages.py. Would be good to clean those up.
| @@ -43,7 +43,6 @@ nav: | |||
| - Set up environment: using_eessi/setting_up_environment.md | |||
| - Basic commands: using_eessi/basic_commands.md | |||
| - Demos: using_eessi/eessi_demos.md | |||
| - EESSI in CI: using_eessi/eessi_in_ci.md | |||
There was a problem hiding this comment.
Not sure why this was removed here, but this has a conflict with upstream that needs to be resolved anyway. I guess that'll sort this out too.
| default_handler: python | ||
| handlers: | ||
| python: | ||
| paths: [src/test-suite] |
There was a problem hiding this comment.
This could also be shortened to paths: [test-suite], see the above changes.
| uses: actions/checkout@v4 | ||
| with: | ||
| repository: eessi/test-suite | ||
| path: src |
There was a problem hiding this comment.
Why don't we just do this without path, i.e. in the current workdir? It will still clone into a subidr test-suite by default right? No need to nest that further inside a src I'd think.
| @@ -1,6 +1,9 @@ | |||
| # documentation: https://help.github.com/en/articles/workflow-syntax-for-github-actions | |||
| name: deploy documentation (only on push to main branch) | |||
| on: | |||
| schedule: | |||
There was a problem hiding this comment.
Actually, I don't think we want this in the regular deploy.yml. Having a cronjob that directly deploys the API docs means we have no human in the loop to check the changes to the API docs, and whether they make sense. I think the way this was implemented for the software overview in https://github.com/EESSI/docs/blob/main/.github/workflows/update_available_software.yml makes more sense for now: do a build of the docs, then create a PR based on that. It means the auto-generated docs will actually be part of this repo, i.e. the physical *.md files will be files within the EESSI/docs repo. That'll allow us to do a check on them before they get deployed.
Long term, we might want to do this fully automatically, without human in the loop. But to start with, I think the human in the loop would be a good thing (even if someone needs to keep an eye on those PRs and merge them).
There was a problem hiding this comment.
I think the main change I'd suggest here is to not do the API docs generation as part of the deploy.yml, but in a way similar to how the update_available_software.yml workflow works (i.e. copy that workflow, and adapt it to generate the API docs instead of the available software list). This workflow creates a PR to EESSI/docs every X time (on a cronjob), which allows us to have a human in the loop to check what was generated and if that makes sense.
In the future, we could even see if the workflow could be triggered on push to the main branch of EESSI/test-suite. It seems something like that should be possible https://medium.com/hostspaceng/triggering-workflows-in-another-repository-with-github-actions-4f581f8e0ceb but that's no priority right now.
A dependency of this PR is on EESSI/test-suite#192 as PR 192 resolves the build error for API docs