Feature - Example CMDBs

[RossMurr4y]

Creating issue ticket for discussion on the best approach.

The hamlet docs have a need for some example CMDBs (account and products seperated out) for use within the tutorials, the getting started guide and others. These CMDBs would ideally be used for as much as possible, including during a hamlet build itself to ensure that our existing documentation is always up-to-date and we aren't pushing code that breaks the way the documentation says it should work. I think it would also make sense that the same CMDBs are the ones that hamlet developers are encouraged to develop with (if they are thorough enough then we wouldn't have much need to maintain other CMDBs.

Another usage that I have thought of for such example CMDBs is in the reference docs that outline the file structure of the CMDB. As hamlet versions change, so will the structure of the CMDB inevitably. We could ensure that the docs always reflect the latest CMDB structure by using tooling such as Markdown Magic Directory Tree. With an updated build script for the docs site that cloned the CMDBs first into the docs structure, this could be pointed at them and create a tree-like display of the CMDB. Pair this with a daily CI/CD build on the example CMDB's to ensure they are always the latest structure the docs would always present the very latest CMDB structure with no effort. Granted that this would likely require a few fake files like credentials.json in order for them to actually show up, and we'd not want to be actually deploying any of those CMDBs templates however I think the effort-to-benefit ratio is high.

Currently the "Ministry of Silly Walks" CMDBs are used for this purpose and I'd be happy to reuse them here. I do think they need a clean up because I'm pretty sure that I've made a mess of things there since working on the project. This does give us the opportunity to come up with something hamlet related to use as the topic for all of the example CMDBs too.

[ml019]

In COT, we had a "patterns" repo which evolved into the collection point for cookie cutter projects for cmdbs. Thinking we continue this and version this in synch with gen3 itself.

The CLI is integrated with cookie cutter now I believe (or can be) so we could have a CLI command to assist in getting the right version of the patterns.

I think we will need to address the question of capturing the Hamlet version in the repos themselves so the CLI can drive off the currently available version of gen3.

[RossMurr4y]

I think we will need to address the question of capturing the Hamlet version in the repos themselves so the CLI can drive off the currently available version of gen3.

I think we do need the hamlet version in the repo for sure. I think its only valuable up to a certain extent though - you want to know if you are out of date, but we don't want people going looking for docs for older versions. @roleyfoley and I discussed this a while back. Docusaurus - the tooling used for the docs site - allows for versioning of our docs. We discussed using this but decided that the whole point of hamlet is to keep up with cloud advancements. So whilst I think we want people to be able to easily identify if they are on an older cmdb structure we don't necessarily want to do too much with that info other than tell them to run updates.

Looking over the patterns repo, I can see how it would be useful. Will add a few steps to the build process though if the repo is still to be used to build directory tree documentation. I'm also not sure that the build tooling on the Zeit site will have access to run docker commands which would be required to run cookiecutter through the CLI. Going down this path would likely require moving to a new docs deployment solution.

[roleyfoley]

We do have support in the cli for the cookie cutter templates using the cot generate command
I think we could still integrate the dynamic documentation building with ziet, we would have documentation jobs on the source repos of the documentation ( patterns, or engine ) and its deploy process would be to commit to the docs repo. That way the docs site publishing still runs independently from the documentation process.

Essentially we make our code repo's contributors to the documentation in the same way that we do

[RossMurr4y]

Great - that sounds good. I've created a directory to house such content in the docs repo. It needs to live in the right spot within the repo else it wont end up in the final build.

@roleyfoley looks like cot generate will be straight forward enough. Do you think we could add placeholder CMDB's to the CLI build pipeline now just using --use-default, publish them to this repo in the examples dir provided and we'll update the cot generate commands with more specific content for the guides once we've worked out what we want in them?