Multirepo mkdocs versioning
adibrastegarnia opened this issue · comments
Hi,
I have a quick question. I am using mkdocs to build a website for docs from multiple repo by collecting docs (using submodules) and then build them. I would like to know if I want to use this plugin to apply versioning in this case, do I need to create branches and push the new changes to each branch?
An example:
https://github.com/multirepo-docs/root-docs
Do you want to apply versioning on each repo or only on the global repo?
@ldez
Thanks for your quick response. We build one website for all of the repos. We would like to have versioning for the global repo which presents all docs from other repos together. That means whenever we click on one version, we should be able to see the same website (i.e. same page tree) but different version. For sure that means we need to clone a specific version for each repo to build the global one (i.e. after each release in other repos).
For example, if we release v1.0 of three repos (three subsystems) then we would like to have all docs with version v1.0 from other subsystems (i.e. other repos) to build v1.0 representation in the global repo (i.e. website). I hope I explained it well. Each release in other subsystems should give us one representation of docs in the global website.
Please look at this website which is built by collecting multiple repo docs and then build the website:
https://multirepo-docs.github.io/root-docs/
and here is a simple script which does that:
https://github.com/multirepo-docs/root-docs/blob/master/build_docs.sh
In this case:
projectA v1.1.0
projectB v1.0.0
projectC v0.5.0
what is, for you, the content of each version of the "metaproject" ?
A. metaproject v1.0
projectA v1.0.x
projectB v1.0.x
projectC (no v1.0 so skipped)
or
B. metaproject v1.0
projectA v1.0.x
projectB v1.0.x
projectC (v0.5.x because it's the current version)
There are a lot of questions by trying to create versioning for the global project, maybe it's a bit off-topic.
In all cases, you need to have one branch per version (of the global project) if you are trying to create the versioning at the global project level.
Thanks. I was thinking the same thing that a new branch will be needed to have the contents for that version from all repos. And one more question: when we run these two commands:
curl -sfL https://raw.githubusercontent.com/containous/structor/master/godownloader.sh | bash -s -- -b "${GOPATH}/bin" ${STRUCTOR_VERSION}
structor -o containous -r traefik --dockerfile-url="https://raw.githubusercontent.com/containous/traefik/v1.7/docs.Dockerfile" --menu.js-url="https://raw.githubusercontent.com/containous/structor/master/traefik-menu.js.gotmpl" --rqts-url="https://raw.githubusercontent.com/containous/structor/master/requirements-override.txt" --force-edit-url --exp-branch=master --debug;
Do we also need to run mkdocs related command (e.g. mkdocs gh-deploy -v --clean --remote-name gh-token;)?
structor creates only the documentation, so you have to publish it.
But as structor built the doc, mkdoc cannot publish it.
There are a lot of tools to publish the doc on gh-pages.
Take a look how we do that with Traefik: https://github.com/containous/traefik/blob/master/.travis.yml
@ldez
I found some time to try it out but I ran into an issue. When I generate the website, it generates a master directory but there is no index.html file on top of gh-pages. Here is the log from travis. gh-pages has just one folder which is named master.
Initialized empty Git repository in /tmp/d20191013-7949-slcz0g/work/.git/
Switched to a new branch 'gh-pages'
cd -
cd /tmp/d20191013-7949-slcz0g/work
commit 0e2cddd970945eeefbc82929606dc42c6f1a0ed6
Author: Deployment Bot (from Travis CI) <deploy@travis-ci.org>
Date: Sun Oct 13 14:34:59 2019 +0000
Deploy multi-repo-docs-versioning/root to github.com/multi-repo-docs-versioning/root.git:gh-pages
master/404.html | 305 +++++++++++++++++++++
master/assets/fonts/font-awesome.css | 4 +
master/assets/fonts/material-icons.css | 13 +
master/assets/fonts/specimen/FontAwesome.ttf | Bin 0 -> 165548 bytes
master/assets/fonts/specimen/FontAwesome.woff | Bin 0 -> 98024 bytes
master/assets/fonts/specimen/FontAwesome.woff2 | Bin 0 -> 77160 bytes
.../fonts/specimen/MaterialIcons-Regular.ttf | Bin 0 -> 128180 bytes
.../fonts/specimen/MaterialIcons-Regular.woff | Bin 0 -> 57620 bytes
.../fonts/specimen/MaterialIcons-Regular.woff2 | Bin 0 -> 44300 bytes
master/assets/images/favicon.png | Bin 0 -> 521 bytes
...
To give you more context: in travis.yaml file if I specify site/master when we want to deploy it then content will be published but you used site. I am wondering how it works for your case
@ldez
I figured that out. One more question:
Can we use structor locally as well to build the website and check it?
Yes you can use it locally.
resolved