update eyre documentation

[tinnus-napbus]

removes old documentation and adds a scry ref, data types ref, external
& internal api ref, and examples.

@drbeefsupreme

[tinnus-napbus]

note this requires the change to faq.md in urbit/urbit.org#642 in order for zola to build it successfully

[Fang-]

Wow! Another big-boy PR right here. Very thorough, complete and clear documentation. Thank you for this!

The only thing I'm really missing here is some description of the header handling that Eyre does for you. CORS headers come up implicitly, but the behavior isn't talked about in too much detail (and extends to OPTIONS requests wholesale). Eyre respects the Forwarded header when figuring out the address for inbound requests (but only if the request came from localhost). Additionally, Eyre (and/or the runtime?) take care of the content-length header for you.

I also left some corrections, and a bunch of suggestions and style nits in the comments below. Hope they're useful, and let me know if you want me to further clarify on anything here. (:

[basilesportif]

@tinnus-napbus fang had some changes requested here, wanted me to re-ping you

[Fang-]

All good changes so far, thank you!

[tinnus-napbus]

ok I've addressed most of the comments. The original point about covering Eyre's CORS capabilities I've DM'd @Fang- to discuss what is necessary.

On the point about spider, yeah it's technically true that the spider interface isn't directly a function of Eyre. It is kinda a de facto thing though, it's automatically bound and threads are kinda fundamental despite spider not being a vane itself. My feeling is that practically it's useful to have all the documentation of web interfaces in one place and the previous "using eyre" documentation covered threads. I probably could find a place for it in the threads documentation though, idk. What do you think @drbeefsupreme ?

On the point about the explanations of Eyre's behaviour wrt generators bound with %serve and agents bound with %connect, maybe it's not ideal to have that info on the tasks page but idk it's useful and I'm not sure where else to put it. I think putting it all in the examples page isn't the best, nor on overview because it's too technical. I could create another document that covers the %serve and %connect cases in more detail but then I'm not sure there's enough info to warrant a separate page. What do you think @drbeefsupreme ?

[tinnus-napbus]

also sorry for not addressing this stuff earlier, I missed github's email about it and assumed nobody had got around to reviewing stuff

[Fang-]

Thank you for all your work and changes here! This looks good to go, once @drbeefsupreme has settled the remaining discussion here and given his blessing.

On the point about spider, yeah it's technically true that the spider interface isn't directly a function of Eyre. It is kinda a de facto thing though, it's automatically bound

Counterpoint: it's only automatically bound if the spider app is started, and many apps bind endpoints when they start, and many apps are started by default. We're not talking about file-server here either, even though that's arguably even more fundamental (functionality-wise) than spider.

[drbeefsupreme]

Pretty much all very minor grammar nitpicks. One of the task entries was also incomplete. Other than that, LGTM!

[tinnus-napbus]

all the issues raised by @drbeefsupreme have been fixed