Proposal: Eliminate redundancy between documentation.json and docs/*.json

[jvoigtlaender]

Right now, for each package there is a documentation.json file and additionally for each module of the package a docs/ModuleName.json file. As far as I can tell, the latter are redundant in terms of information: The content of ModuleName.json is an excerpt of documentation.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 from docs/ModuleName.json rather than the whole documentation.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 whole documentation.json. In fact, https://github.com/elm-lang/package.elm-lang.org/blob/master/frontend/Page/Module.elm now reads both documentation.json and docs/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:

• Issues like https://github.com/elm-lang/elm-package/issues/153 would be fixed even on old module pages. Because that error with the wrong printing of union types is only present in the docs/ModuleName.json files, not in documentation.json.
• Faster rendering of the module pages. Right now, since both documentation.json and docs/ModuleName.json are read, and come back asynchronously, the view function is called twice in main = 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, because modulesAndMentionedTypes.signal and documentation.signal fire independently. Getting both the "modules and mentioned types" and the "documentation for the specific module" information from a single read of documentation.json would lead to only one call of the view function.

Am I missing something? Is there an important, still relevant, reason for having the duplication of information between documentation.json and the docs/*.json files?

[evancz]

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.

[jvoigtlaender]

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.

[evancz]

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.

[evancz]

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.