Centralized documentation repository conflicts with separate versioning

[pmai]

Describe the bug

While drawing all kinds of documentation into one repo is fine for overview purposes, this directly clashes with separate versioning and release cycles of the individual repositories: E.g. the OSMP specification is at 1.0.0, and is unlikely to change in lock-step with OSI releases, since changes to OSMP are only seldomly needed. By moving the OSMP Specification Document out of the OSMP repo, and replacing it with just a simple README that references the osi-documentation version of said document, there is no longer a stable connection between the rest of the OSMP repo (e.g. the examples) and the corresponding specification document, which was formerly the case.

So in order to do a new OSMP release, which usually necessitates changes to the spec and updates to the examples, we'd now have to do a release of both OSMP and osi-documentation in lock-step, which is unlikely to happen, since osi-documentation will have many unrelated changes in the meantime, not all of them release ready. And users of the examples will have to manually look for the corresponding spec document, since the reference in the OSMP README is not version-specific.

The same problem is likely to occur for the other tools, like osi-visualizer which is likely to have releases in between OSI releases.

And this is likely even true for osi itself, since the link between releases of the seperate repos is tenuous, IMHO.

Taken together the changes break the assumption of atomicity and integrity of git repos, IMHO.

Describe the expected behavior

Each repo must be self-contained, in that matching specification, documentation and source code must be maintained in the repositories themselves, and can be referenced by central documentation hubs if wanted (e.g. using git submodules).

[vkresch]

@pmai yes this is a good point, thanks for your feedback :).
Currently we have a folder structure in the osi-documentation repo similar to the organizational structure (osi, osi-visualizer, osi-validation, osi-model-packaging). How about we move these folders directly into the respective repositories and use the osi-documentation repo to parse each repo to generate the documentation. Every repo will have it's own self containing documentation. If we want to document general information about the osi organization we will still use the osi-documentation repo for it. To keep the documentation always up to date independent of the release cycles of each repo osi-documentation will have a chron job which will weekly (or even daily) parse each repo of the organization to contain always the latest documentation changes. This way developers don't need to worry to clone two repositories to contribute to the organization.

[pmai]

That seems like the best way to go forward I'd say, since it keeps the documentation together with the sources, while keeping a centralized documentation setup and site.

[jdsika]

Very good compromise!

[jdsika]

I think we have to adjust the contributor guidelines explaining what documentation goes where.

General things about the project -> osi-documentation "general"
Specific information about OSMP -> osi-sensor-model-packaging "doc/*"

[jdsika]

@vkresch so only visualizer is missing and we should integrate the proto2cpp repo. Cleanup the readme there as well. IF it is still used for the documentation generation it should be mentioned in the docs.

[vkresch]

I mentioned in the contributors' guide how the documentation is being generated for osi, osi-visualizer and osi-validation. For now I documented this:

• Documentation changes can be performed by anyone.
• Consider adding stuff to the osi-documentation or directly to the doc folder in the repository.
• When new changes are made directly to the osi-documentation repo the documentation will be rebuild and the new changes can be seen. When making documentation changes in the doc folder of the repository the changes will be visible when the daily chron job of osi-documentation is executed.

[vkresch]

@jdsika for now I just include the README of proto2cpp into sphinx that's all. I think we don't need an extra doc folder for it since the README is sufficient enough.

[jdsika]

agree.