Decouple website + documentation

[davidgraeff]

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.

[ghys]

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]

we're reaching the limit of our current plan with Netlify and trying to keep the bandwidth down.

Maybe more static stuff can be served by public CDN? I mean you can easily push logos, images, css to npm and several public CDNs will start to serve it. Might help.

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.

Ok that explains this script. I guess that can be taken care of.

due to assets being duplicated

I assumed that docs.openhab.org would reference www.openhab.org static resources. Only the actual doc pages are served from the subdomain. It's just that the website has another release cycle.
It might even be good to have addons.openhab.org as well. That way the website fully stays in cache until a new blogpost gets released.

Using subdomains doesn't mean that we wouldn't share assets. But the logic to build each part could be more specific and doesn't need to take all other parts into account. For example addons2: We merge about every 2 days something to master. Only a master merge would ever need to trigger the addons.openhab.org build script and a rate limit might throttle that down to once a day.

[ghys]

Maybe more static stuff can be served by public CDN? I mean you can easily push logos, images, css to npm and several public CDNs will start to serve it. Might help.

Except the website redesign was in part due to GDPR compliance and we would like to keep the privacy policy as straightforward as possible - so no external CDN if we can help it (the Twitter feed on the homepage is a notable exception to this rule but mentioned in the privacy policy terms).

Having a single VuePress site is probably easier maintenance (Webpack and al) but if there are clearly better ways to do it I'd be happy to consider them.

[5iver]

The documentation for the helper libraries was recently migrated to Sphinx (BSD license), and I am very happy with it. I had planned a large update to the Automation pages, but have shelved those changes due to limitations in the platform used for the OH docs. Specifically, the use of tabs (#183), which is included in Sphinx.

Sphinx would not only work for the static docs, but is a documentation generator and there is a Sphinx extension for Java, if we decide to not setup JavaDoc.