Move automatic documentation generation into a separate repo

[ararslan]

As its name implies, AWSCore is core AWS functionality. However, there is a significant portion of code in src/AWSAPI.jl that automatically generates documentation and other packages, which (at least to me) seems out of scope. I would propose that this be done separately in some kind of "meta" repository.

[iamed2]

What about calling it "AWSAPI"?

[ararslan]

Yeah, I didn't mean we should call it "meta," I meant that it is a meta-repository of sorts. AWSAPI sounds good to me.

[ararslan]

Looks like the AWSAPI.jl, AWSMetadata.jl, HTML2MD.jl, and Makefile files in src can all be moved and removed. The Makefile does the deployment (and references command that won't exist on the vast majority of users' systems) and AWSMetadata.jl and HTML2MD.jl are only used in AWSAPI.jl.

[ararslan]

Oh wait, AWSAPI is used to generate Services. Hm.

[iamed2]

For AWSSDK, AWSAPI is used to generate it but the generated code lives in the repo. Could do the same thing here?

[ararslan]

How would the workflow look then to update AWSCore based on AWSAPI? You'd have to run it manually locally, right?

[iamed2]

Yes

It could record the version/treehash of AWSAPI used to generate it in a comment.

[ararslan]

WIP: https://github.com/JuliaCloud/AWSAPI.jl

[samoconnor]

Hi All, I'm just back from summer break.
FWIW botocore includes API model stuff: https://github.com/boto/botocore/blob/develop/botocore/model.py, so keeping this stuff in AWSCore.jl does not seem out of scope to me.
However, now that it's moved, I don't have a strong argument for un-moving it.

In AWSCore.jl, the API model stuff is all done off-line, resulting in static generated code and docs.
Boto does some API model interpretation on-the-fly. It may eventually be useful to do this kind of thing in AWSCore.jl, but if we get to that point, we can always copy the relevant moved pieces back to here.

[samoconnor]

@ararslan can you please:

• either keep the Makefile, or put some notes in the README that explains how to run the generator,
• put a reference to the new repo in a comment in Services.jl
• rename the new repo to something more obscure :) ... I'm worried that AWSAPI might look like it is the top level Julia interface for accessing AWS APIs. Perhaps AWSAPIMetadata, or AWSAPIModel ?
• put a statement in the README that directs people who just want to use an AWS service to the right place.

[ararslan]

Welcome back! I hope you had a nice summer. Meanwhile in the northern hemisphere, we've been freezing. 😄

Do note that AWSAPI is still an experiment at this point; all of the relevant functionality is still in AWSCore. I didn't think it would/should be moved until AWSAPI is fulfilling all of our needs. If it's better not to move it at all, that's fine, I just thought it made more sense to have a dedicated place to do all of the automated generation stuff.

[samoconnor]

Cheers!
Lets move it, I think it'll be better that way in the long run. Best to keep AWSCore.jl lean and simple particularly if the automated generation stuff is going to grow in complexity.

[mattBrzezinski]

Closing this issue as it's no longer relevant. The AWSAPI.jl package was created.