Unpublished PyPI

[jacastello]

Team,

Thanks for your hard work on this project! It really helps me and my team develop more efficiently for backstage because we can count on understanding the way the docs are going to look like before we submit them.

The Issue

I noticed that the last merge failed to publish this package to PyPI. I think that's likely because of some interesting dependency handling. Here's the relevant part of the build logs

Checking ./dist/mkdocs_techdocs_core-1.5.1-py3-none-any.whl: PASSED
Checking ./dist/mkdocs_techdocs_core-1.5.1.tar.gz: PASSED
Uploading distributions to https://upload.pypi.org/legacy/
Uploading mkdocs_techdocs_core-1.5.1-py3-none-any.whl
WARNING  Error during upload. Retry with the --verbose option for more details. 
ERROR    HTTPError: 400 Bad Request from https://upload.pypi.org/legacy/        
         Can't have direct dependency: markdown_inline_graphviz_extension@      
         git+https://github.com/cesaremorel/markdown-inline-graphviz.git@579f10a
         f9fe7[187](https://github.com/backstage/mkdocs-techdocs-core/actions/runs/12075049793/job/33674158694#step:6:193)c717c20615f65774f898c1a0d. See                                 
         https://packaging.python.org/specifications/core-metadata for more     
         information.

From the requirements.txt I can see that you've tried to pin a git hash for the graphviz extension.

...
mkdocs-material==9.5.46
markdown_inline_graphviz_extension@git+https://github.com/cesaremorel/markdown-inline-graphviz.git@579f10af9fe7187c717c20615f65774f898c1a0d
mkdocs-monorepo-plugin==1.1.0
...

Possible Solutions

One possible solution is to set dependencies more loosely for the requirements you actually depend on being stable, and allowing these other packages freer reign to install themselves using the requirements.txt syntax with ~=.

Another would be to move this project to a pyproject.toml management like mkdocs uses.

If I have some time, I'm happy to submit a PR.

[awanlin]

Hi @jacastello, thanks for taking the time to log this. I'm aware of this issue but at the time my plate was too full to be able to follow up and address it and sadly still is but wanted to share what I know.

The root issue is really just markdown-inline-graphviz-extension which hasn't seen updates since last year and is a fork itself of markdown-inline-graphviz which hasn't seen updates in 9 years.

Given this my thinking has been:

1. We drop this from mkdocs-techdocs-core. This seems like the simplest solutions but for those that use it they would need to add it back which could be a burden. Wish we had stats on how much these features are being used as it would really help with decisions like this.
2. Backstage TechDocs Maintainers create a proper fork under a different name that allows us to publish new versions and use that going forward. This option does not seem feasible as the Backstage TechDocs Maintainers as a small team as it is with a large workload.
3. The broader Backstage Community creates a proper fork under a different name and publishes updates accordingly. I haven't seen anyone where or know of anyone that I think would take this one so that sort of puts this at a dead end.

With your comments we could look at that but I'm not sure it addresses the root issues that's causing us to be unable to publish. We have some security concerns around pulling in code arbitrarily and being able to use the commit sha would at least give us some confidence that the code won't change.

[johnphilip283]

Hey there @jacastello! Just to keep releases moving along for mkdocs-techdocs-core while still maintaining strict security requirements, the maintainers have decided that we will fork the markdown-inline-graphviz-extension, release a new package under a new name in PyPI and use that instead here. We should be undertaking this work soon, and we'll update this issue as it lands.