Closed jvoigtlaender closed 8 years ago
Seems reasonable. You are correct about the initial reasoning.
I'm working on a revamp of the site right now, so I was thinking about this as well.
I'll share the stuff I'm working on (called the revamp
branch) that is moving things to elm-html, the new elm-markdown, and the Elm Architecture. Lots of stuff has yet to be transferred over, but I guess it'd be good to share.
If (and when) you want me to make the changes to avoid creation and use of the docs/*.json
files, let me know which branch to target.
It's all on revamp
but I'm trying to work on this myself, I've had a lot of days that are like 30% handling issues and it is not good for me. I did two days of no email and felt a lot better than in a while.
I closed because I think I'm gonna do this. Or at least we have had the conversation about whether it's a good idea for not. If I mess it up, let's open another one later.
Right now, for each package there is a
documentation.json
file and additionally for each module of the package adocs/ModuleName.json
file. As far as I can tell, the latter are redundant in terms of information: The content ofModuleName.json
is an excerpt ofdocumentation.json
(and easily found in there if desired).Why do the
docs/*.json
files exist? One reason I can imagine is an attempt at optimization for efficiency: When rendering a module page (rather than the package page), one only reads and parses the information fromdocs/ModuleName.json
rather than the wholedocumentation.json
. Is that the sole reason? If so, it is obsolete. In the course of recent improvements like https://github.com/elm-lang/package.elm-lang.org/pull/60 and https://github.com/elm-lang/package.elm-lang.org/pull/91, it already became necessary for the module page renderer to also read and process the wholedocumentation.json
. In fact, https://github.com/elm-lang/package.elm-lang.org/blob/master/frontend/Page/Module.elm now reads bothdocumentation.json
anddocs/ModuleName.json
. It processes the former for some information, and also extracts information from the latter. But that latter, it could directly take from the former just as well.Two knock-on benefits from going the route of doing away with
docs/ModuleName.json
stuff:docs/ModuleName.json
files, not indocumentation.json
.documentation.json
anddocs/ModuleName.json
are read, and come back asynchronously, theview
function is called twice inmain = Signal.map3 view Window.dimensions modulesAndMentionedTypes.signal documentation.signal
in https://github.com/elm-lang/package.elm-lang.org/blob/master/frontend/Page/Module.elm, becausemodulesAndMentionedTypes.signal
anddocumentation.signal
fire independently. Getting both the "modules and mentioned types" and the "documentation for the specific module" information from a single read ofdocumentation.json
would lead to only one call of theview
function.Am I missing something? Is there an important, still relevant, reason for having the duplication of information between
documentation.json
and thedocs/*.json
files?