git.iko.soy/gogol
on develop help sign in
Reworking README to be consistent with Amazonka
3e22577Brendan Hay
README.md+26−27
compare with develop
unifiedsplit
@@ -8,6 +8,9 @@ under heavy development and not intended for public consumption, caveat emptor!
8[![Gitter Chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/brendanhay/gogol)
8[![Gitter Chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/brendanhay/gogol)
9
9
10* [Description](#description)
10* [Description](#description)
11+* [Documentation](#documentation)
12+* [Organisation](#organisation)
13+* [Change Log](#change-log)
11* [Contribute](#contribute)
14* [Contribute](#contribute)
12* [Licence](#licence)
15* [Licence](#licence)
13
16
@@ -17,45 +20,38 @@ under heavy development and not intended for public consumption, caveat emptor!
17<img alt="Гоголь-моголь" height="261px;" src="https://upload.wikimedia.org/wikipedia/commons/c/c7/Kogel_mogel.JPG">
20<img alt="Гоголь-моголь" height="261px;" src="https://upload.wikimedia.org/wikipedia/commons/c/c7/Kogel_mogel.JPG">
18<img alt="Мико́ла Васи́льович Го́голь" height="261px" src="https://upload.wikimedia.org/wikipedia/commons/3/31/NV_Gogol.png">
21<img alt="Мико́ла Васи́льович Го́голь" height="261px" src="https://upload.wikimedia.org/wikipedia/commons/3/31/NV_Gogol.png">
19
22
20−## Generate New API Endpoints
23+A comprehensive Google Services SDK for Haskell supporting all of the publicly
24+available services.
21
25
22−To generate new API endpoints, use the gogol/gen directory.
26+An introductory blog post detailing the motivation can be found [here](http://brendanhay.nz/gogol-comprehensive-haskell-google-client).
23−The key files in this directory (outside of the actual gogol-gen source!) are the annex files.
24
27
25−To add a new endpoint, first create its annex file in the annex directory. It should be named after the API endpoint as found in the <a href="https://www.github.com/google/google-api-go-client">google/google-api-go-client repo.</a>
28+## Documentation
26
29
27−### Example:
30+You can find the latest stable release documentation for each respective library
31+on Hackage under the [Google section](http://hackage.haskell.org/packages/#cat:Google).
28
32
29−#### Generating the Cloud Dataproc API
33+Haddock documentation which is built by CI from the `develop` branch
34+can be found [here](http://brendanhay.nz/gogol-doc).
30
35
31−The Cloud Dataproc API is called `dataproc-api.json` in the Google Discovery API.
32−Create the file `./gen/annex/dataproc.json` with these contents:
33
36
34−```
37+## Organisation
35−{
36− "library": "dataproc",
37− "canonicalName": "Dataproc"
38−}
39−```
40
38
41−From the `./gen` directory, run:
39+This repository is organised into the following directory structure:
42
40
43−```
41+* [`gogol`](gogol): Actual operational logic, you'll need to import this to send requests etc.
44−make clean
42+* `gogol-*`: Data types for each of the individual Amazon Web Service libraries.
45−make
43+* [`core`](core): The `gogol-core` library upon which each of the services depends.
46−```
44+* [`examples`](examples): A currently sparse collection of examples for the various services.
45+* [`gen`](gen): The code generation binary, along with configuration, templates, and assets.
46+* [`script`](script): CI scripts to manage the release lifecycle of the service libraries.
47+* [`share`](share): Makefile plumbing common to all service libraries
47
48
48−This will build the `./gen/bin/gogol-gen` executable, and then will generate libraries
49+> See the `./gen` subdirectory for further details about generating an API client/SDK.
49−for all APIs that have matching `./gen/annex/*.json` configuration.
50
50
51−Once completed, the result would be a `./gogol-dataproc` directory containing the
52−generated API client.
53
51
54−`make full-clean` can be used to cause a complete re-download of all (including new)
52+## Change Log
55−service models.
56
53
57−Individual libraries can be generated by passing a specific `MODELS` environment
54+A change log for the entire project can be found under [`gogol/CHANGELOG.md`](gogol/CHANGELOG.md).
58−variable to the `make` command, for example: `MODELS=model/admin/directory/v1/admin-api.json make`
59
55
60
56
61## Contribute
57## Contribute
@@ -66,3 +62,6 @@ For any problems, comments, or feedback please create an issue [here on GitHub](
66## Licence
62## Licence
67
63
68Gogol is released under the [Mozilla Public License Version 2.0](http://www.mozilla.org/MPL/).
64Gogol is released under the [Mozilla Public License Version 2.0](http://www.mozilla.org/MPL/).
65+
66+Parts of the code are derived from AWS service descriptions, licensed under Apache 2.0.
67+Source files subject to this contain an additional licensing clause in their header.
gen/README.mdnew file+52
@@ -0,0 +1,52 @@
1+# gogol-gen
2+
3+For pull requests which affect generated output, please _do not include_ the
4+actual regenerated service code, only commit the updates to the generator,
5+config and annex connection.
6+
7+This ensures the Continuous Integration process is the single source of truth
8+for generated code changes, and keeps pull requests readable and focused on
9+actual generator code/logic changes.
10+
11+## Generating
12+
13+The configuration for the generation step of each individual service endpoint lives
14+under `./annex`. The naming matches the Google Discovery Service naming of endpoints,
15+which are vendored under `./model`.
16+
17+Rather than actually crawling the Discovery Service, the [Google API Go Client](https://www.github.com/google/google-api-go-client)
18+is vendored under `./vendor`, and the JSON service definitions are copied to `./model`
19+to ensure reproducibility of the generation steps and the abilitry to diff across versions.
20+
21+### Example: Cloud Dataproc
22+
23+To add a new endpoint, first create the related JSON configuration in the `./annex` directory.
24+
25+Since the Cloud Dataproc API is called `dataproc-api.json` in the Google Discovery API,
26+you would create the configuration `./annex/dataproc.json` with the following contents:
27+
28+```
29+{
30+ "library": "dataproc",
31+ "canonicalName": "Dataproc"
32+}
33+```
34+
35+Then, the `Makefile` is used:
36+
37+```
38+make clean
39+make
40+```
41+
42+This will build the `./bin/gogol-gen` binary, and will generate a Haskell library
43+for each API that has matching `./annex/*.json` configuration.
44+
45+For the above example, the result would be a `../gogol-dataproc` directory at the
46+top-level of the project containing the generated API client.
47+
48+> `make full-clean` can be used to cause a complete re-download of all (including new)
49+service models.
50+
51+> Individual clients/SDKs can be generated by passing a specific `MODELS` environment
52+variable to the `make` command, for example: `MODELS=model/admin/directory/v1/admin-api.json make`