[Appendix]Maybe add a new Remark/Atom Tutorial to Contribution Section

[Confectrician]

Sorry i didn't find a better headline.

Basic Idea is inspired from: #423
Related: #418, #196, #50
Also: #530 as a parallel and a bit different approach.

I am not working on Atom yet but want to change to this environment.
I do many things alright already, nevertheless some validation and error notifications would be nice.
Also it would be nice to have some kind of page with good informations for for new contributors to give them a starting point.

So maybe it would make sense to add some kind of FAQ or Overview,
of how the Page is build,
of what is markdown and kramdown,
of what is remark and what is linting
and finally what is a possible Environment for contributing here with some direct feedback from the editor.

I know we have the repo Readme file already and there is some topic overlap to the points above.
But it is very technical and it maybe would be a bit bloated if we fill in all those mentioned things.

This is of course just an early idea and feedback, improvements or additions are welcome as always.

[ThomDietrich]

Sounds good!
Most of these details can go into the README. I agree that they shouldn't be too technical and that would be okay.
Markdown related content should go into: https://github.com/openhab/openhab-docs/blob/gh-pages/styleguide.md

[bgilmer77]

Is there a place already where the linter and its installation and operation are discussed? I found it once, but now I cannot locate it.

[ThomDietrich]

At that time I've documented the linter right in the configuration file. That is of course not a good position and whoever does work on this issue may move these details 😃 https://github.com/openhab/openhab-docs/blob/gh-pages/package.json

[ThomDietrich]

Btw. I was also looking into integrating the whole linting process into the continuous integration process. I did not make any progress there but that would also be an interesting step. Before that we should however try to resolve most issues. There are thousands of errors thanks to the various binding READMEs. I did not start working on these yet but that would definitely be something.

Last note regarding the remark config: I am currently not happy with the linting rules for lists (e.g. the forced loose list style is not always a good choice). I might change this setting soon, feel free to propose improvements.

[Confectrician]

That's why i wanted to get atom running here locally.
Just to get an impression of how big the problem is. 😄

Maybe we could add those informations splitted to the "correct" files and add some summary article with readme and styleguide as a link.
I like this even more than my initial thought.

First some general information about the process/workflow and then some more detailed information in the detailed files separated by topic.

[Confectrician]

@ThomDietrich

I have installed and configured atom and all necessary packages and node modules, but the linting doesn't seem to recognize the package.json settings.

Is there anything special to do additionally?

[ThomDietrich]

no just the steps documented inside the package.json file. What happens when you open a console for the openhab-docs directory, then type:

npm install
npm run-script lint-md

[bgilmer77]

FWIW, installed Atom and lint-md on my Mac with no problem. I tried to install it on a Ubuntu 16.04 Desktop and am getting errors and the linter is not active. When I get a moment I will post the errors here.

[bgilmer77]

Interesting - reran npm install and npm run-script lint-md, and now Atom errors are gone. But...

on Ubuntu 16.04, running npm run-script lint-md on a fully updated system produces the following:
node v4.2.6
npm v3.5.2
...
[email protected] lint.md: "remark ."
spawn ENOENT
Failed at the [email protected] lint-md script "remark .".

Attached is the error log...
npm-debug.log

[bgilmer77]

I would be happy to take a crack at writing something about the linter, starting by just pulling the text from the package.json file. But where should it go? I think it should go into a Contributing article, but there are two of them - one in the main documentation, and one in the developers guide. Thoughts?

[Confectrician]

I would go for a new article in the main documentation.
Developers guide is a special area where not everyone will look in.
And docs contributions can perfectly done by non developers too.

About the atom issues:
I didnt have to time to check it yet, but will keep you updated here.

[ThomDietrich]

Whoever moves the linter instructions somewhere more meaningful, please add the following option to run the linter over a certain directory:

node_modules/.bin/remark concepts configuration index.md

[bgilmer77]

I have started an outline for this article. That’s why you’re getting all the questions from me on it. Will put up a PR once I have the basics down.

[ThomDietrich]

Regarding the where: I'd move as much content as possible into README.md.

[bgilmer77]

So you want linter info in the README?