Enhancing the ESH copying process

[ThomDietrich]

Continuing #56

Would it be better to have the whole eclise smarthome docs as a submodule (to make realtions clear to everyone) and to work with symlinks (if jekyll and friends like that)? Without symlink an idea would be to have an sh script (like you have now) copying files with an additional step, marking them as copied. An added YAML front matter "page.source" in the head of the file would be a nice approach I guess.

And to answer your question, yes I think so, we should copy as much as possible but add openhab specific things on top. A styles2.css loaded after style.css could be a place for everything orange and openhab'y.

---

to work with symlinks (if jekyll and friends like that)?

I think this won't work, at least I wasn't very successful when I experimented with such a solution.
What we will indeed need sooner or later is a better manageable copy mechanism, doing it in the pom.xml as it is now will definitely become too complex at some point in time.

I think we should copy as much as possible

Feel free to adapt the copy mechanism accordingly.

---

Will have to find the time for that.

[ThomDietrich]

@kaikreuzer bringing this back to life. You don't have to read the above, just answer me this real quick:
The update.sh script currently pulls the other repos which are included as submodules, then copies over relevant content.
In my opinion the submodule solution brings more problems than benefits. Are there any arguments against removing them and temporarily cloning the repos inside the script?

[kaikreuzer]

"temporarily cloning" sounds if it will take much much longer. At the moment, the script only does a pull of the latest changes and it is very quick to do an update.
What kind of issues do you see with the submodules? They are merely a reference to other repos and by default not being checked out, so they do not impact the "real" repo in any way.

[ThomDietrich]

If or if not a submodule is checked out (by default) is sadly depending on your git clients configuration. Mine does it by default, I can only imagine others do the same.

Ideally only a pull of the latest changes is needed. You are assuming that the submodules were cloned before, which is (see above) not normally the case. I get that you are referring to your setup as you are running the update script regularly.

In general I don't see the submodules help clarify things. They are not "part" of the project, which would normally be the meaning of a submodule. They also do not serve as a reference. When I started out working with the openhab-docs repo I did not understand their impact and expected them to be some twisted part of the documentation, which is not the case. I had to understand that they are solely used by the update script. Contributors shouldn't be bothered with this.
I want to include further documentation from the openhabian and the habpanel repo and would hence have to (1) add the submodules and (2) modify the update script. This doesn't seem clear and a closed process.

I would prefer to remove the submodules and to build a complete update script, containing

• clone commands
• the whole migration and modify process
• deletion of the temporarily cloned repos
• initiation of the git commit of generated content

As the update script already is a bash script and uses the git command, I do not expect this change to have a negative impact on the usefulness of the script in e.g. automated processes or CI efforts in the future, which was my main concern here.

[kaikreuzer]

I am ok with removing the submodules, but I would wish that the update script does not do a temporary cloning, but that it only clones the repos in a specified path if they aren't there already - if they already exist, the latest changes should be pulled only. This way we can keep the processing quick as it is today without bothering any docs contributors with it.

[ThomDietrich]

Sure thing 😉
I'll look into this soon.