A suggestion to look for a :marg property in project.clj to specify an ordering of namespaces to render override, e.g.:
:marg [org.foo.z.core org.foo.y.help org.foo.x.util]
would result in namespaces being rendered in the marg doc in that order, instead of in (sort) order as returned by find-clojure-file-paths
Not sure I like the :marg key, but I like the behavior. Patches welcomed.
I suspect a topological sort based on the namespace dependency graph (with lexical order breaking ties) would achieve most of what people want by default.
As a default, sure, but the reason to offer the ability to specify the ordering is to allow the human language story and the code story to be managed orthogonally. In a small way I think that's one of the areas where lp has gone wrong- lp is right to point out that the key ideas behind an application are often best communicated in a big picture sense in a narrative into which bits of the code should fit, and also that documentation embedded in code is often locally helpful and globally useless. But knuth's and others' lp workflow goes too far in that direction, in requiring code to be authored in a way that's primarily concerned with narrative; for most code authoring use cases for most people, that's the wrong approach.
Marginalia does a really nice thing in making a single readable artifact that's beautiful and that includes both narrative and code, but it is primarily a narrative, so it seems like the ordering of that narrative should be independently controllable.
Anyway, that's where the original suggestion came from....
Have been busy but will try to provide a simple patch that uses a vector of namespaces in project metadata for narrative ordering in the next week.
Here's a first pass