monorepo with submodules (empty)

[dhabierre]

Hi,

I am playing with monorepo plugin. I have 1 repo (rpa-doc) with 2 submodules (rpa-1, rpa2):

rpa-doc
- docs \ README.md
- .gitmodules
- catalog-info.yml
- mkdocs.yml
- rpa-1 @ d70d...
- rpa-2 @ dbe6...

mkdocs.yml

site_name: RPA Documentation (Test)

nav:
  - Home: README.md
  - Submodules:
    - rpa-1: '!include ./rpa-1/mkdocs.yml'
    - rpa-2: '!include ./rpa-2/mkdocs.yml'

plugins:
  - monorepo

rpa-1 @ d70d...

- docs \ README.md
- mkdocs.yml

When backstage executes the doc generation:

[mkdocs-monorepo] The file path /tmp/backstage-QFfxej/rpa-1/mkdocs.yml does not exist, is not valid YAML, or does not contain a valid 'site_name' and 'nav' keys.

And /tmp/backstage-QFfxej/rpa-1/mkdocs.yml does not exist. => Submodules folders are empty.

I think the clone action does not use the --recursive attribute.

Locally:

git clone https://bitbucket.[xxx].[xxx]/scm/tests/rpa-doc.git --recursive

=> [OK] submodules are pulled and mkdocks.yml files exist.

git clone https://bitbucket.[xxx].[xxx]/scm/tests/rpa-doc.git

=> [KO] submodules are empty

Any idea? Thanks!

[dhabierre]

If backstage doesn't use --recursive attribute when cloning the repository (when updating the documentation), how to auto-execute the git submodule update --init --recursive command after the clone?

I don't know how monorepo processes when retrieving the main repository and the submodules.

[dhabierre]

• https://github.com/backstage/mkdocs-monorepo-plugin/issues/89

[agentbellnorm]

Hi @dhabierre, I assume you are using backstage with "local" generation, e.g. backstage generates the documentation files when you visit the documentation page?

This is one of the two ways to set up techdocs, and this way is not recommended for production use. You can read more here

Once you are using the recommended setup (ci/cd), it should be fairly straight forward to configure your build server to also download the submodules (our builds do this today)

That said, as others have mentioned in #89, this plugin is not responsible for checking out the files. It's handled by the techdocs node plugin, here (using different implementations depending on which source control system is used). If you want to proceed with this approach, feel free to create a PR in the node plugin!

[dhabierre]

Hi @agentbellnorm,

I assume you are using backstage with "local" generation, e.g. backstage generates the documentation files when you visit the documentation page?

You are right, this is the current setup but I can't change it, I am not the operator of the backstage instance. So I can't use a custom CI in order to clone the repository, then get the submodules with a second git command.

[bih]

As this is out of scope for this plugin, I'm closing this.