wmalgadey
[Feature]: Create github pages with Code Coverage report
Describe the Feature
We could create github pages for this project, to display some information like
- Documentation / Usage of the library
- Code Coverage report
Why Is This Feature Useful?
see #104
Proposed Solution
I would like to use https://www.11ty.dev
Alternatives Considered
All types of static site generate would be good enough I guess.
Additional Context
Add any other context, screenshots, or examples that help explain your request.
Checklist
- [x] I have searched the existing issues and discussions to ensure this is not a duplicate.
- [x] I have provided a clear and concise description of my feature request.
- [x] I have included any relevant examples or details to support my proposal.
Thank you for helping to improve PyTado! 🚀
Not a contributor to this repo, but as I've recently been going through several phases of organizing the documentation for https://github.com/kritsel/tado-openapispec-v2 I simply want to share my experience. Use or ignore as you like :-)
Start
- Started out with putting all relevant documentation in README.md. Resulting in a README which was getting far too big.
- Had the need to publish at least 2 pieces of additional content: 1) Swagger UI (html page) and 2) Test report of integration tests
Solution 1: publish to GitHub pages via gh-pages branch
Started to experiment with GitHub pages for only static content by using the gh-pages branch. Did not spend too much time on it.
Didn't quite like the separate branch, too much implicit magic. Stopped the efforts before I even started thinking about how to cover my additional documentation needs.
Solution 2: publish to GitHub pages via workflow.
My repo is basically a maven project with integration tests written in Kotlin. Maven can build a local site with a combination of static content plus all kinds of code related reports such as an integration test report. I started using that to create a site with all relevant static documentation, test reports and Swagger page in my GitHub workflow, and deploy it to to GitHub pages via the actions/deploy-pages@v4 action action.
As time went by I started to dislike the fact that my static documentation was part of my git repo. Making changes to documentation should be easy, it shouldn't require a build pipeline with git commands (maybe even forcing pull requests if you want to treat your main branch with the proper respect) (this is my personal opinion, other people will have other preferences).
Solution 3: use GitHub pages for dynamic content, use the repo's Wiki for static content (current state)
I enabled the Wiki functionality for my repo to manage all static content, and shortened the text in the README: https://github.com/kritsel/tado-openapispec-v2/wiki The site generated by Maven and published to GitHub pages is still used, but only for the dynamic content (test report) and HTML based content (Swagger UI): https://kritsel.github.io/tado-openapispec-v2/failsafe-report.html
Having a split in GitHub Wiki content and GitHub page content is not ideal, but then no solution is perfect. For now I'm sticking with this solution.
@kritsel thank you for your feedback. I am a fan of static site generators and like the idea of a documentation in markdown which renders nicely to a static webpage and will be hosted on github. But it's not me adding content here (I hope 😄).
So @palazzem or @erwindouna what do you think?
Thanks for sharing @kritsel! We'll have to look into the solutions and work this out to get a fitting direction. @wmalgadey I used the shield and codecov.org to store and display the code coverage. Have you also seen this?
@inverse, maybe we should remove the failing workflow to push the test results to the PR comment and go @erwindouna way and use codecov.org?
ok, I made the jump :D --> https://app.codecov.io/github/wmalgadey/PyTado
