Improve shortcomings of current setup

[laurensgroeneveld]

The current setup is fairly simple:

• Checkout bcc-documentation-base (this repository)
• Checkout local repository that has docs ("docs repository")
• Copy across docs to the vuepress folder in bcc-documentation-base
• Build a VuePress site from that folder

This works quite well for basic documentation that is attached to a repo. To add a VuePress site is only three steps. However there are several shortcomings with this approach:

• It is impossible to run VuePress locally from the docs repository, so it is not possible to preview the website before pushing. Note: this might be alleviated with branch deploys (mentioned here)
• Including Vue components from the docs repository is only possible if they don't have external dependencies, because we don't have anything to do with the package.json in that repository and instead use that one in the vuepress folder.

I'm curious how we can improve on this setup. I think we should keep in mind the following goals for this setup:

• Documentation lives as close to the code as possible (i.e. in the same repository, not some centralized docs repository)
• It's as frictionless as possible to add a documentation site to a project. If you have an existing docs folder, it should be plug-and-play (i.e. add a GitHub action)

I would rather not include VuePress as a dependency in all the other repositories, as it rather defeats the "frictionless" goal (especially when your code isn't Javascript and doesn't have a package.json already).

One final thing to consider is that some of this sprang forth from a discussion on the developer.bcc.no repository: bcc-code/developer.bcc.no#57 - this repository is a special case as it's intended as a website with generic documentation, without any attached code. Perhaps this repository should not use the same setup as the other repositories. Still, other repositories would benefit from us solving the problems with local running and including Vue components.

[Ghostbird]

We could use git submodules in the main documentation repository to store a reference to an actual git commit in the other repositories.

Disadvantages:

• Slightly more complex technology
• Doesn't auto-update when the submodule documentation is updated (I'm not sure the current set-up does that either)
• Not possible to build the documentation for only a specific repository, in that repository.

Advantages:

• There's only one repository to build (the main documentation) it references the other repositories as submodules and can access all their files.
• Points to git-ref, so you can be flexible in your references. Point it to a tag as done right now, or point it to an exact commit hash. Or just point it to a branch name to always use the latest from that branch.

That's quite a different set-up than this template mechanism though.

[laurensgroeneveld]

Thanks, good suggestion!

Doesn't auto-update when the submodule documentation is updated (I'm not sure the current set-up does that either)

The current setup also doesn't do this, but when a build is triggered in a repository it will automatically pick up any changes to the VuePress setup.

I do like the idea of pointing to a branch with a git submodule, I actually didn't know that was possible. Still, we'd have to take into account that a push to a repository needs to trigger a rebuild of the site.

In a way this feels pretty close to the current setup, while not solving the two pain points of running a doc site locally and importing Vue components with dependencies, so not sure if it's worth the effort.

[Ghostbird]

Yeah, I agree. I though it pertinent to mention git submodules, as they're a good fit for some of the things we do here. However, it doesn't solve the the issue of being able to run a doc site locally. However, it does allow you to run the main docs locally, with an updated git submodule reference to your branch. Then you can make local changes, push to your branch, run the full docs build and see your changes relatively easily. No need to perform any actions that permanently change anything to any deployed environment. Maybe that's a slight improvement over the current set-up. You won't have to copy files over manually multiple times, only change the git submodule reference once.

[leo-schick]

I have another idea to solve this:

Why not add a docker-compose file into repo developer.bcc.no which clones bcc-documentation-base into the container and mapps the local data (e.g. developer.bcc.no) into the pace where you need it? @laurensgroeneveld

[laurensgroeneveld]

Why not add a docker-compose file into repo developer.bcc.no which clones bcc-documentation-base into the container and mapps the local data (e.g. developer.bcc.no) into the pace where you need it?

Doesn't sound like a bad idea 👍