REST service
wkeese opened this issue · comments
The old API viewer had a REST service to embed API documentation in the reference doc. Do we still want that?
Like http://dojotoolkit.org/api/rpc/1.8/dojo/dom, although for some reason it isn't working there, but Kitson has it working on his local box.
The code is (or was) in https://github.com/wkeese/api-viewer/blob/master/rpc/index.php.
Just to quote our email discussion and make sure I have this tracked and understand as it's obviously an important requirement:
On Fri, Apr 19, 2013 lbod wrote:
-
can you send me a link to where this happens - "The ref loader gets HTML snippets"?
I think http://dojotoolkit.org/reference-guide/1.8/dojo/_base/array.html
-
Is it server side aggregation i.e. resttructredtext aggregated server side or xhr loading of snippets from the api?
Yes, and yes. When the reference guide is generated (on a server) it makes REST calls to the web service https://github.com/wkeese/api-viewer/blob/master/rpc/index.php
So you said "do we still want that?", I'm presuming there's a strict dependency on the API viewer because of the ref guide and therefore a strict dependency on urls. I feel the question is for you.
If it's not wanted then how does the ref guide get that information as it'd be a breaking change if it's not included?
Yeah, I agree, we still need that feature for the ref guide, assuming @kitsonk still wants to support ref guide pulling in of API data.
I hadn't realised there was this tight coupling and certainly something I'd break if you hadn't said. It's worth questioning why the ref guide does this seeing as you've created a nice exporter that's much more easily read than markup output based on a similar datasource
Perhaps historical reasons. Actually I didn't realize that RPC service was returning JSON. @kitsonk, perhaps the ref guide generator should just access the details.json export from the doc parser, currently at https://github.com/wkeese/js-doc-parse/commits/exporter ?
If the reference guide is the only reason for the RPC, then I would say drop it. If there is a concept though that other devs might want to consume the API as a RESTful service it might be a nice feature.
I haven't built anything yet into dojoment.
Closing this as it looks like requirement is not needed, reopen if necessary