search

openhab / openhab-docs

This repository contains the documentation for openHAB.
https://www.openhab.org/docs/
Other
272 stars 688 forks source link

Markdown code validation #50

Closed ThomDietrich closed 3 years ago

ThomDietrich commented 8 years ago

There are occasional problems from markdown documents to a correct presentation on http://docs.openhab.org. Examples https://github.com/eclipse/smarthome/pull/1873 and https://github.com/openhab/openhab2-addons/pull/1159. From a general standpoint, it would be good to have some Markdown Style Guides for docs in place.

I would suggest including a Markdown linter into the build process, possibly even as Pull Request validator. Options:

kaikreuzer commented 8 years ago

Would be cool. Any suggestion which one of the three and how to configure it to match the requirements of Github Pages for docs.openhab.org?

ThomDietrich commented 8 years ago

I think it would be amazing to have some even more complex style matching in there. One could easily*\ build linting rules to have all binding readme's in the same structure, with "Full Example" at the end and all.

The first project seems nice and clean. Rules are extendable.

The second seems to be a less feature rich clone of the first, but in node vs. ruby.

The third is on another level. It's an addon for "remark" and there are a lot more addons for that. What I like about this one from skimming the Readme: You can define exceptions in your markdown files if (for some reason) one linting warning should be suppressed at one point and remark allegedly will tidy up markdown files, fixing linting problems on its own (good or bad? Can't say)

I have no experience with any of these. The first one might be enough, the third may be awesome.

What are the limitations if one wanted to include one of these into the PR validation, is this realistic? Yes, a big part of the documentation is imported, but I still think this would help a lot.

kaikreuzer commented 8 years ago

Yes, I also like the idea a lot. If you have the time to experiment a bit with it (e.g. in a test repo of your own), it would be gorgeous. I am afraid that I won't find the time to look into this myself any time soon...

ThomDietrich commented 8 years ago

I'll look into it. Just to be sure, please tell me if such a tool could be integrated into the contribution process. I saw that you are using a jenkins setup on cloudbees, so i guess the possibilities there are very limited?

kaikreuzer commented 8 years ago

If there are suitable hooks for Github to trigger such a check, we will be able to do it. Yes, we currently use cloudbees for openHAB 2 PRs to do a test build of them, at ESH there is actually Travis in place since a few weeks.

The easiest integration would probably be to include it in the Maven build itself, then these tests would also be executed for local builds, before people actually create the PRs. Does any of these tools offer Maven integration?