What's your experience using this?

[tsibley]

Hi! I found this Sphinx extension by happenstance while trawling thru PyPI looking for something else, but it caught my eye because I've been interested for a while in how to make an "umbrella" project in Sphinx that shares a unified TOC tree with its sub-projects. This looks like the closest thing I've seen!

I'm curious, if you're willing, to learn more about how this extension has worked (or not) for you. It looks like it was originally written for and used by the https://ngs-smap.readthedocs.io project, but not any more? I'd appreciate any insight you have into tackling multi-project integration with Sphinx!

[DriesSchaumont]

Hi @tsibley, thanks for reaching out! You are correct that this extension was originally developped for ngs-smap. However, I am no longer involved with the smap project, and I only got to play with sphinx-subprojecttoctree myself for a small amount of time. So even my experience is limited 😅 . I think that this project (AFAIK) is not longer being used anywere; you're correct that the ngs-smap project moved all of the documentation into a single repository. I can only guess, but I think they run into some bugs that I solved later on (but that they could not wait for it). Also, if I recall correctly, creating a 'full' local build where links to a subproject are created to a another local copy instead of the online webpage is difficult to do/currently not implemented. This makes large restructures to both the master project and the subprojects at the same time difficult. I could test this and/or document this, but its currently not one of my priorities.

Regarding my experience with this plugin: I think it works OK, especially for the hack that it is. Sphinx makes it hard to extend the behavour of the toctree directive, and I think I saw some comment from a sphinx maintainer somewhere that they are reluctant to touch or refactor it because of its complexity. But the combination with interspinx to solve the cross-references is nice.

Becaue this plugin is no longer in use, you are very welcome to try it and provide feedback. I have an example (check out this and this), that still works. However, you will encounter this bug, for which there is a workaround/solution that I did not include in the examples. I mention it here for completeness.

P.S.: For most of my recent documentation projects I moved to quarto, which IMO is more versatile compared to sphinx (it uses a markdown flavor, though; not .rst). No idea if they have subproject support, though.

[DriesSchaumont]

Also, I just enabled the discussions for this project, so lets take this over there 🎉