I have always found sphinx challenging, in usability or syntax :( It could be probably much more advanced, but I went for pdoc3 for api docs and mdbook for documentation in general.

What I really hope that exists, is a system where I can reuse the documentation (sections) in other pages, ergonomically

I built that system multiple times to do preprocessing with things like including parts or special linking or referencing images from anyhwere

https://github.com/xmonader/publishingtools/tree/development...