My approach:

1. put a one line comment at the top of each code file.

2. The build extracts that comment and dynamically updates a readme.md for the directory that describes each code file.

3. The build also produces a master document that includes the same summaries in a single document.

This provides a light indication of what each code file is and how they are organized into directories. It doesn’t provide any indication of flow control or any kind of logical linking.

Since the documentation is prepared via automation you can add new files or delete files and the documentation remains current. If such a comment is missing from a code file the build fails with error messaging. Keeping each comment up to date is still manual though.

Interesting approach.

Do you have an example repo?