search

backstage / mkdocs-monorepo-plugin

✚ Build multiple documentation folders in a single Mkdocs. Designed for large codebases.
https://backstage.github.io/mkdocs-monorepo-plugin/
Apache License 2.0
319 stars 74 forks source link

Is additional configuration required in order to use Git Submodules? #89

Closed carlreid closed 1 year ago

carlreid commented 1 year ago

I have a situation where I am able to execute python -m mkdocs serve and have a monorepo documentation site run with no problem (even with a fresh clone).

However, when it comes to execution in backstage, I get something like: [mkdocs-monorepo] The file path /tmp/backstage-0tvdBh/my-other-repo-submodule/mkdocs.yml does not exist, is not valid YAML, or does not contain a valid 'site_name' and 'nav' keys.

My guess right now is that the clone of the repository isn't including --recurse-submodules and therefor has no content, but I am also unsure on where I should look for this or enable this. Do I have to modify something else in backstage to properly support Git Submodules?

whiskeysierra commented 1 year ago

This mkdocs plugin is not responsible to perform the git checkout, is it? Whatever tool you're using to do that, it should be configured there.

carlreid commented 1 year ago

I agree and I don't believe it is responsible, but I had no idea where else to try ask/look. As far as I am aware it "should just work" if you read the documentation here in the README, as it states no other requirements anywhere.

Edit: I think this might relate to the use of "URL Reader" which is probably downloading the ZIP from the GitHub repo. The downloading of the ZIP won't include the submodules.

whiskeysierra commented 1 year ago

Git submodules are a very different beast. My advice is to avoid them completely.

carlreid commented 1 year ago

I think I will wait for https://github.com/git/git/pull/1359 which should add recursive archiving of the repo. With the intent of closing https://github.com/dear-github/dear-github/issues/214. That would mean the URL Reader in backstage will get the "full picture" of the repository and will no doubt build fine.