ghys
commented
5 years ago Anything to improve the convoluted docs build w/ Maven, a Groovy script, a shell script, and then a Ruby script (!) is good, the approach sounds fair, a drop-in replacement that the website could place in the right place with as little logic as possible would be very nice. Remember there are still a lot of Jekyll specifics in the Markdown files that were designed for the old docs (structure & syntax), the Ruby script has a few tricks to make them Vuepress-friendly (in process_file mostly. The better way would be to take care of them at the source, but unless that's done the tricks have to stay.
Spin up a second netlify for doc.openhab.org (Change the DNS CName of the openhab.org domain accordingly)
No merging the two former sites was a good decision and has its advantages, that would mean maintaining yet another site with its dependencies, and would increase the necessary bandwidth due to assets being duplicated - we're reaching the limit of our current plan with Netlify and trying to keep the bandwidth down.
We can however have other sites for different versions of the docs, and could discuss which one appears by default. It is possible in Netlify to set up different domains for different branches. Currently the latest docs are the default but there are several issues with that - most people use the stable or milestone versions and the newer add-ons are not relevant to them. (I kind of like the way https://vuetifyjs.com/ does it - they have sites for their "next" branch, and another one for their "dev" branch.). Having the latest stable/snapshot as default would reduce drastically the frequency of builds and bandwidth for the main site. However, improvements to the general docs should be immediately visible, unless they are relevant to the next/snapshot version. It's a complicated matter but probably best discussed in the openhab-docs repo.
davidgraeff
5iver
This will solve some issues and allow easier maintenance.
I have this in mind:
Spin up a second netlify for doc.openhab.org (Change the DNS CName of the openhab.org domain accordingly)
The documentation repo build instructions will clone the website repo (for the styling and vuepress stuff). This makes the docu team independent of the website build cycle. And we can add whatever we need on the docu side to vuepress for better documentation.
Let the addon repos generate a summery off all bindings and docs etc on each master push and let us upload that artifact to bintray (move the responsibility to us OH2-addons maintainers to serve that file instead of the docu or website team to crawl us).
Whenever the website is build (cron triggered once a day is best I guess) it collects the bintray artifact, moves the included markdown files to the correct position and uses the bundled json or whatever metadata for whatever else need to be done.