backstage / backstage/mkdocs-monorepo-plugin

Question about Python dependency resolution when using the monrepo plugin with mkdocstrings plugin

Open
#71 6 comments 1 reaction 0 assignees View on GitHub
Dominant language
Python
Stars
400
Forks
80
PR merge metrics
No merged PRs in 30d

Description

Hello there,

We make use of a plugin called **mkdocstrings** to generate documentation for the source code. This plugin loads the different Python libraries mentioned in the source code during the documentation generation process. As a result of this, there are Python dependency resolution issues that we encounter when using the monrepo plugin in a root repository . If the mkdocs.yaml file in the root repository references multiple mkdocs.yaml files from different repositories, we run into dependency resolution errors as there are conflicting dependency requirements in the different repositories.

The code in each of the different repositories uses different versions of the same Python module. Hence, the issue.
I am wondering that this must be an issue at a lot of organizations.
How is this overcome elsewhere?

To overcome this, we were thinking that the docs folder in each of the different repositories should be processed independently and the output of the mkdocs build command should be copied to some place in the root repository and then have mkdocs somehow assemble the documentation. I am not sure if this is even possible. If someone has already done this, please respond back.

Thanks,
Kiran Hegde

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the root mkdocs.yaml references, the separate repositories' mkdocs.yaml files, and the docs folders involved in the mkdocs-monorepo-plugin setup. Reproduce the conflicting Python dependency requirements during mkdocs build, then determine whether independently building each docs folder and assembling the outputs can be supported; the issue does not define a settled implementation or completion criteria.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
15/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.