Description
Right now each author of a library has to host their generated API documentation somewhere, using either something like GitHub Pages or a custom website. This is annoying for both maintainers due to the extra maintenance required and for users as their documentation is now scattered all over the place.
The usual answer to this is some sort of centralized API documentation platform such as https://docs.rs/ for Rust. While this makes it easier for both maintainers and users, it puts the burden on the maintainers of the platform, which is likely the same group of people also maintaining the underlying language.
In our current state I'm not convinced this burden is worth it or even sustainable. For one there's the financial cost that comes, but there are also potential security issues that need to be dealt with when cloning random repositories. We'd also have to make sure to not exhaust resources such as disk space, something that's surprisingly tricky to do with just pure Git.
It may make more sense to have inko init optionally include some CI config to automatically publish to GitHub Pages/Codeberg Pages/whatever, that way at least we don't have to cover the costs. The downside of such an approach is that versioning the documentation becomes more difficult, as not having a dedicated branch for output means you essentially overwrite/regenerate the entire website from scratch on each deploy.
All in all, I'm not sure yet what the best approach is at this point.
Related work
No response
Description
Right now each author of a library has to host their generated API documentation somewhere, using either something like GitHub Pages or a custom website. This is annoying for both maintainers due to the extra maintenance required and for users as their documentation is now scattered all over the place.
The usual answer to this is some sort of centralized API documentation platform such as https://docs.rs/ for Rust. While this makes it easier for both maintainers and users, it puts the burden on the maintainers of the platform, which is likely the same group of people also maintaining the underlying language.
In our current state I'm not convinced this burden is worth it or even sustainable. For one there's the financial cost that comes, but there are also potential security issues that need to be dealt with when cloning random repositories. We'd also have to make sure to not exhaust resources such as disk space, something that's surprisingly tricky to do with just pure Git.
It may make more sense to have
inko initoptionally include some CI config to automatically publish to GitHub Pages/Codeberg Pages/whatever, that way at least we don't have to cover the costs. The downside of such an approach is that versioning the documentation becomes more difficult, as not having a dedicated branch for output means you essentially overwrite/regenerate the entire website from scratch on each deploy.All in all, I'm not sure yet what the best approach is at this point.
Related work
No response