I've been working on this tool for a while that makes documentation easier and faster. The main idea is to have the code itself be the driver. Would love some feedback: https://trymaniac.com
This is something that I’ve felt is going to become very hot - some way of ensuring that documentation never goes stale. In the same vein as tests needing to pass before merging a commit, ensuring documentation is up to date when commiting. Looking forward to hearing more!
Rust has a feature that somewhat provides this - doctests[1]. Rust doc comments begin with `///` and will be parsed as markdown when generating documentation. If there are codeblocks in the documentation comments, they will be run with all other tests and the test runner will report if the blocks fail to compile or if they error at runtime.
So if the API changes, the example code in the documentation will fail to compile.
I want diagrams of my modules and how things are connected, such as one that shows "types defined in foo.py are used in bar.py". While you're generating docs from code, might think about diagrams.
Have you tried Pyreverse[1]? I used it for my Software Engineering course. From the documentation - Pyreverse analyses Python code and extracts UML class diagrams and package dependencies.