Just don’t tell me “you can see the context” as any proper codebase would probably not be linear in code flow anyway.
For instance, I group all include or equivalent statements in an appendix, rather than within the primary code discussion. If a block of code can't be directly reused, but for some reason needs to be in every (or several) source files (think standard boilerplate), I'll write it once in a place that makes sense, and reference it from all the places where it actually gets tangled into the output.
Additionally, I include the Makefile (or whatever equivalent) and other scripts within this same document. Learning docker? Make a dockerfile in here, fully annotated, along with the shell commands to actually deploy it.
Mine will only mirror the original source tree if it's:
Very simple.
I've imported a bunch of code into it and don't, yet, know how to break it down.
An example C project may look like:
* Purpose Statement
* README
* Usage
This program can be executed from the command line by calling:
#+BEGIN_EXAMPLE
$ ./foo
#+END_EXAMPLE
It accepts the following command line parameters:
- =-c= :: something
- =-d= :: something else
** Implementation
To process the command line flags we use <some library>.
it has the following API calls...
Here's the code for processing our commands...
* Business Logic
We communicate with the server via some REST API described in <location>
and <library> to make the calls.
-- Here I'd intermingle the REST API I'm using and the C API I'm producing
-- for my own consumption, or something similar.
* Code that's not fully organized yet
** Main Function
This is the entry point, blah, blah, blah:
#+BEGIN_SRC c :noweb yes :tangle src/main.c
#+END_SRC
* Appendix: IncludesSome people use several Emacs windows (or frames or whatever) but all of them peeking into the same file, but in to different locations of it.