Docs: update readme (#61)

palantir · Oct 29, 2018 · a5a4ab7 · a5a4ab7
1 parent 853796a
commit a5a4ab7
Showing 1 changed file with 64 additions and 82 deletions.
diff --git a/README.md b/README.md
@@ -1,91 +1,33 @@
-# Gradle-Conjure
+# Gradle Conjure ![Bintray](https://img.shields.io/bintray/v/palantir/releases/gradle-conjure.svg) [![License](https://img.shields.io/badge/License-Apache%202.0-lightgrey.svg)](https://opensource.org/licenses/Apache-2.0)
 
-A gradle plugin that allows easy usage of the Conjure toolchain within Java projects
+_Gradle Conjure is a build tool which allows defining and generating code for Conjure APIs in Java projects._
 
-## Getting Started
-To apply the plugin, in your top level `build.gradle` file, add a buildscript dependency on Conjure.
+## Overview
 
-```gradle
-buildscript {
-    repositories {
-        maven {
+gradle-conjure is a set of Gradle plugins which allow you to define and consume Conjure-defined APIs easily.
 
-            url 'https://dl.bintray.com/palantir/releases/'
-        }
-    }
-    dependencies {
-        classpath 'com.palantir.gradle.conjure:gradle-conjure:4.0.0'
-    }
-}
-```
+- [`com.palantir.conjure`](#compalantirconjure) allows API authors to easily define APIs and generate bindings for Java, TypeScript and Python.
+- [`com.palantir.conjure-publish`](#compalantirconjure-publish) allows API authors to publish a Conjure definition as a single self-contained file.
+- [`com.palantir.conjure-local`](#compalantirconjure-local) allows API consumers to locally generate bindings for Conjure API definitions.
 
-Then create a new project for your API with the following directory structure
-```groovy
-your-project-api
-├── build.gradle
-├── your-project-api-objects/
-├── your-project-api-jersey/
-└── src/
-    └── main/
-        └── conjure/
-            └── your-project-api.yml
+## com.palantir.conjure
 
-```
+To see how to add gradle-conjure to an existing project, please see our [getting started guide][].
 
-With the following `build.gradle`
-```groovy
-apply plugin: 'com.palantir.conjure'
-```
+### Tasks
 
-Then update your `settings.gradle`
-```diff
- rootProject.name = 'your-project'
+- **compileConjure** - Generates code for your API definitions in src/main/conjure/**/*.yml
+- **compileConjureObjects** - Generates Java POJOs from your Conjure definitions.
+- **compileConjureTypeScript** - Generates TypeScript files and a package.json from your Conjure definitions.
+- **compileIr** - Converts your Conjure YML files into a single portable JSON file in IR format.
+- **compileTypeScript** - Runs `npm tsc` to compile generated TypeScript files into JavaScript files.
+- **publishTypeScript** - Runs `npm publish` to publish a TypeScript package generated from your Conjure definitions.
 
- include 'your-project'
-+include 'your-project-api'
-+include 'your-project-api:your-project-api-objects'
-+include 'your-project-api:your-project-api-jersey'
-```
-_Note, you can omit any of these projects if you don't need the generated code (gradle-conjure just looks at the project name suffix to figure out where to put generated code).  For example, if you only want to generate Java objects, you can just add the `your-project-api-objects` project and omit the others._
-
-For guidance on how to write `your-project-api.yml` please see the [Conjure Source Files Specification][]. 
-
-Once applied you can configure the versions of the generators to use manually or through the use of dependency recommendation.
-
-##### Manual Configuration
-Add the following to the root gradle file.
-```groovy
-subprojects {
-    configurations.all {
-        resolutionStrategy {
-            force 'com.palantir.conjure:conjure:4.0.0'
-            force 'com.palantir.conjure.java:conjure-java:1.0.0'
-            force 'com.palantir.conjure.typescript:conjure-typescript:3.0.0'
-        }
-    }
-}
-```
-
-##### Dependency Recommendation
-If you are using nebula.dependency-recommender, add the following to the version recommendation file.
-```
-com.palantir.conjure:conjure = 4.0.0
-com.palantir.conjure.java:conjure-java = 1.0.0
-com.palantir.conjure.typescript:conjure-typescript = 3.0.0
-```
+### Extension
 
-## Usage 
-Gradle-Conjure provides the following tasks:
-- compileConjure - Generates code for your API definitions in src/main/conjure/**/*.yml
-- compileConjureObjects - Generates Java POJOs from your Conjure definitions.
-- compileConjureTypeScript - Generates TypeScript files and a package.json from your Conjure definitions.
-- compileIr - Converts your Conjure YML files into a single portable JSON file in IR format.
-- compileTypeScript - Runs `npm tsc` to compile generated TypeScript files into JavaScript files.
-- publishTypeScript - Runs `npm publish` to publish a TypeScript package generated from your Conjure definitions.
-
-Gradle-Conjure also exposes the `conjure` extension, which allows you to configure the behaviour of each supported
-generator. You configure the generator by specifying properties in a corresponding named closure. These properties 
-are converted into command line options or flags and passed on to the generator CLI. 
+`com.palantir.conjure` also exposes a `conjure` extension, which allows you to configure the behaviour of each supported
+generator. You configure the generator by specifying properties in a corresponding named closure. These properties
+are converted into command line options or flags and passed on to the generator CLI.
 
 The supported closures are:
 - `java` - Configuration for [Conjure-Java][]
@@ -99,22 +41,62 @@ conjure {
     typescript {
         version = "0.0.0"
     }
-    
+
     java {
         retrofitCompletableFutures = true
     }
 }
 ```
 
-## Publishing
-To enable publishing of your API definition for external consumption, you may use the `com.palantir.conjure-publish`
-plugin instead of `com.palantir.conjure` plugin. This plugin applies `com.palantir.conjure` and also creates a new `"conjure"` publication.
+## com.palantir.conjure-publish
+To enable publishing of your API definition for external consumption, add the `com.palantir.conjure-publish` which applies `com.palantir.conjure` and also creates a new `"conjure"` publication.
+
+
+## com.palantir.conjure-local
+
+### Tasks
+
+- **generateConjure** - Generates code for all Conjure dependencies 
+- **generateTypeScript** - Generates TypeScript bindings for all Conjure dependencies
+- **generatePython** - Generates Python bindings for all Conjure dependencies
+- **generate\<language\>** - Task rule which will generates \<language> bindings for all Conjure dependencies, where \<language\> is the name of the generator to be used
+
+### Configurations
+
+- **`conjure`** - Configuration for adding Conjure API dependencies
+- **`conjureGenerators`** - Configuration for adding generator dependencies
+
+Using the `conjure` extension you can depend upon multiple Conjure APIs at once
+```gradle
+dependencies {
+    conjure 'com.company.product:some-api:1.0.0'
+    conjure 'com.company.other.product:other-api:1.0.0'
+}
+```
+
+Using the `conjureGenerators` extension allows you to use use any Conjure generator which conforms to [RFC 002][]
+
+```diff
+ dependencies {
+     conjure 'com.company.product:some-api:1.0.0'
+     conjure 'com.company.other.product:other-api:1.0.0'
+
++    conjureGenerators 'com.palantir.conjure.postman:conjure-postman:0.1.0'
+ }
+```
 
+For each generator specified referenced by the configuration you must also add a project with the corresponding name
+```diff
+ include 'conjure-api'
++include 'conjure-api:postman'
+```
 
 ## Contributing
 
 See the [CONTRIBUTING.md](./CONTRIBUTING.md) document.
 
+[getting started guide]: https://github.com/palantir/conjure/blob/develop/docs/getting_started.md
+[RFC 002]: https://github.com/palantir/conjure/blob/develop/docs/rfc/002-contract-for-conjure-generators.md
 [Conjure Source Files Specification]: https://github.com/palantir/conjure/blob/develop/docs/spec/source_files.md
 [Conjure-Java]: https://github.com/palantir/conjure-java
 [Conjure-TypeScript]: https://github.com/palantir/conjure-typescript