suggestion: custom aide build-script to autoupdate Static Files

[devmaxde]

This was a quick idea to fix the reoccurring issue of outdated Docs. The Idea here was to use the build script to grab the latest version of the static files.
This will only work, if we have a static url for the trusted files. For example the master branch of the official Repository. That way we don't need to approve each version bump of the Documentation provider.

This should be Locked behind a feature, because this feature requires an Internet connection for building.

Any Ideas?

[lblasc]

I would suggest going with github actions route, by scheduling update of the static files on weekly or monthly basis.

[devmaxde]

But with this we have a lot of smaller releases with only Documentation updates. We could automate it in that way, that the GitHub Actions automate it so that it always opens a Ready to Review PR. But what I saw is, that there isn't an automatic deploy pipeline. So every Month on of the Maintainers has to release it on their own Computer.

[jplatte]

I strongly agree, this should not be part of the build script. I have actually never used this doc integration feature of aide, I wonder how useful it is in the first place. At work we rolled our own, not knowing about this, and it is definitely useful controlling the version of the doc renderer independently of aide.

[lblasc]

From my experience, having the doc integration was initially useful to see aide in action using the provided examples. At work, we also control the scalar doc separately from aide, as we have various customizations.

Pulling the latest static files at build time essentially means that you always want to use the latest version of the doc renderer. This can be achieved by using CDN-served static files. Drawback that I see is that a working internet connection will be required. However, the benefits include the ability to remove all vendored static files and eliminate the need for manual updates. From time to time, there may be potential breakages (see #142 — CSS had to be updated), but it is easier to address those issues than to constantly keep static files updated manually.

[devmaxde]

The Potential breakage only happens, because we use a custom Css extension. For the End user having a standardized up to date version isn't bad. In my proposal the auto update was locked behind a feature --> not the default. If the User requires a Custom Scalar version he shouldn't use the Included Module.

If we implement such a Feature, we remove a lot of work for "us" the Crate Developer and the user, because the update process is automatic. This was the initial intention of my proposal.

[devmaxde]

On the other hand we could provide a CDN solution like Redoc::CDN("./openapi.json") that still has the same function. But using this Method the User still has to have an Internet Connection (When using the Application. Not at compile time) and there might be aditional downtime, if the CDN is down.

And in Theory we could modify the build script to exclude the Internet connection from the compile time. What the build script is trying to do is replace the js and css files.

Another Ideal might be to split the Documentation into another crate. That way we could version it independently of the Aide Library. Currently we need to release an aide version to update the Api.

TLDR:
In my opinion we should provide a easy method for the User to always have a up to date version of the Documentation framework.

[devmaxde]

From my experience, having the doc integration was initially useful to see aide in action using the provided examples. At work, we also control the scalar doc separately from aide, as we have various customizations.

Pulling the latest static files at build time essentially means that you always want to use the latest version of the doc renderer. This can be achieved by using CDN-served static files. Drawback that I see is that a working internet connection will be required. However, the benefits include the ability to remove all vendored static files and eliminate the need for manual updates. From time to time, there may be potential breakages (see #142 — CSS had to be updated), but it is easier to address those issues than to constantly keep static files updated manually.

But #142 is still open. Scalar has't been updated in almost a year. Despite having a ready to merge PR!

[JakkuSakura]

I'm in favor of this feature. We have to repeat PRs like #142 as it's getting not so up-to-date in almost a year