Add documentation for each template (#2)

* template documentation directory structure
* Initial example of a template documentation: the "images-default" template
* move
* some template documentation. Todo: macOS storyboards and strings templates
* small fixes
* storyboards macOS
* correct naming of images doc files
* Strings dot syntax
* Rewrote the "Wha to use it" sections
My view on those sections is to be a checklist for users to see if their situation or the way they use/write the input files matches what is expected by the templates.

For example for strings template, depending on if you're using dot-syntax in your Localizable.strings or not, you might want one template or the other, so that section is supposed to tell you which template to use depending on how you write your keys. In future other string templates we might add bullet points like "If you use underscores in your key names" or "if all your keys in your Localizable.strings are all full-uppercase", etc.

* colors: clarify small bit compared to rawvalue

* document flat string templates

* s/customise/customize/

Documentation/colors/default.md

@@ -0,0 +1,50 @@
+## Template Information
+
+| Name      | Description       |
+| --------- | ----------------- |
+| File name | colors-default.stencil |
+| Invocation example | `swiftgen colors -t default …` |
+| Language | Swift 2 |
+| Author | Olivier Halligon |
+
+## When to use it
+
+- When you need to generate *Swift 2* code
+- Supports _multiple_ color names with the _same_ value
+
+## Customization
+
+You can customize some elements of this template by overriding the following parameters when invoking `swiftgen` in the command line, using `--param <paramName> <newValue>`
+
+| Parameter Name | Default Value | Description |
+| -------------- | ------------- | ----------- |
+| `enumName` | `ColorName` | Allows you to change the name of the generated `enum` containing all colors. |
+
+## Generated Code
+
+**Extract:**
+
+```swift
+enum ColorName {
+  /// <span style="display:block;width:3em;height:2em;border:1px solid black;background:#339666"></span>
+  /// Alpha: 100% <br/> (0x339666ff)
+  case ArticleBody
+  /// <span style="display:block;width:3em;height:2em;border:1px solid black;background:#ff66cc"></span>
+  /// Alpha: 100% <br/> (0xff66ccff)
+  case ArticleFootnote
+}
+```
+
+[Full generated code](https://github.com/SwiftGen/templates/blob/master/Tests/Expected/Colors/default-context-defaults.swift)
+
+## Usage example
+
+```swift
+// You can create colors with the convenience constructor like this:
+let title = UIColor(named: .ArticleTitle)
+let footnote = UIColor(named: .ArticleFootnote)
+
+// Or as an alternative, you can refer to enum instance and call .color on it:
+let sameTitle = ColorName.ArticleBody.color
+let sameFootnote = ColorName.ArticleFootnote.color
+```

Documentation/colors/rawvalue.md

@@ -0,0 +1,54 @@
+⚠️ Deprecated template ⚠️
+
+## Template Information
+
+| Name      | Description       |
+| --------- | ----------------- |
+| File name | colors-rawvalue.stencil |
+| Invocation example | `swiftgen colors -t rawvalue …` |
+| Language | Swift 2 |
+| Author | Olivier Halligon |
+
+## When to use it
+
+- When you need to generate *Swift 2* code
+- When you DON'T have _multiple_ color names with the _same_ value
+
+In contrast to the default colors template, this template generates an enum conforming to the RawRepresentable protocol. Each enum case has, as a value, the 32-bit integer representation of the color.
+
+## Customization
+
+You can customize some elements of this template by overriding the following parameters when invoking `swiftgen` in the command line, using `--param <paramName> <newValue>`
+
+| Parameter Name | Default Value | Description |
+| -------------- | ------------- | ----------- |
+| `enumName` | `ColorName` | Allows you to change the name of the generated `enum` containing all colors. |
+
+## Generated Code
+
+**Extract:**
+
+```swift
+enum ColorName: UInt32 {
+  /// <span style="display:block;width:3em;height:2em;border:1px solid black;background:#339666"></span>
+  /// Alpha: 100% <br/> (0x339666ff)
+  case ArticleBody = 0x339666ff
+  /// <span style="display:block;width:3em;height:2em;border:1px solid black;background:#ff66cc"></span>
+  /// Alpha: 100% <br/> (0xff66ccff)
+  case ArticleFootnote = 0xff66ccff
+}
+```
+
+[Full generated code](https://github.com/SwiftGen/templates/blob/master/Tests/Expected/Colors/default-context-defaults.swift)
+
+## Usage example
+
+```swift
+// You can create colors with the convenience constructor like this:
+let title = UIColor(named: .ArticleTitle)
+let footnote = UIColor(named: .ArticleFootnote)
+
+// Or as an alternative, you can refer to enum instance and call .color on it:
+let sameTitle = ColorName.ArticleBody.color
+let sameFootnote = ColorName.ArticleFootnote.color
+```

Documentation/colors/swift3.md

@@ -0,0 +1,50 @@
+## Template Information
+
+| Name      | Description       |
+| --------- | ----------------- |
+| File name | colors-swift3.stencil |
+| Invocation example | `swiftgen colors -t swift3 …` |
+| Language | Swift 3 |
+| Author | Olivier Halligon |
+
+## When to use it
+
+- When you need to generate *Swift 3* code
+- Supports _multiple_ color names with the _same_ value
+
+## Customization
+
+You can customize some elements of this template by overriding the following parameters when invoking `swiftgen` in the command line, using `--param <paramName> <newValue>`
+
+| Parameter Name | Default Value | Description |
+| -------------- | ------------- | ----------- |
+| `enumName` | `ColorName` | Allows you to change the name of the generated `enum` containing all colors. |
+
+## Generated Code
+
+**Extract:**
+
+```swift
+enum ColorName {
+  /// <span style="display:block;width:3em;height:2em;border:1px solid black;background:#339666"></span>
+  /// Alpha: 100% <br/> (0x339666ff)
+  case articleBody
+  /// <span style="display:block;width:3em;height:2em;border:1px solid black;background:#ff66cc"></span>
+  /// Alpha: 100% <br/> (0xff66ccff)
+  case articleFootnote
+}
+```
+
+[Full generated code](https://github.com/SwiftGen/templates/blob/master/Tests/Expected/Colors/swift3-context-defaults.swift)
+
+## Usage example
+
+```swift
+// You can create colors with the convenience constructor like this:
+let title = UIColor(named: .articleTitle)
+let footnote = UIColor(named: .articleFootnote)
+
+// Or as an alternative, you can refer to enum instance and call .color on it:
+let sameTitle = ColorName.articleBody.color
+let sameFootnote = ColorName.articleFootnote.color
+```

Documentation/fonts/default.md

@@ -0,0 +1,49 @@
+## Template Information
+
+| Name      | Description       |
+| --------- | ----------------- |
+| File name | fonts-default.stencil |
+| Invocation example | `swiftgen fonts -t default …` |
+| Language | Swift 2 |
+| Author | Olivier Halligon |
+
+## When to use it
+
+- When you need to generate *Swift 2* code
+
+## Customization
+
+You can customize some elements of this template by overriding the following parameters when invoking `swiftgen` in the command line, using `--param <paramName> <newValue>`
+
+| Parameter Name | Default Value | Description |
+| -------------- | ------------- | ----------- |
+| `enumName` | `FontFamily` | Allows you to change the name of the generated `enum` containing all font families. |
+
+## Generated Code
+
+**Extract:**
+
+```swift
+enum FontFamily {
+  enum SFNSDisplay: String, FontConvertible {
+    case Regular = ".SFNSDisplay-Regular"
+  }
+  enum ZapfDingbats: String, FontConvertible {
+    case Regular = "ZapfDingbatsITC"
+  }
+}
+```
+
+[Full generated code](https://github.com/SwiftGen/templates/blob/master/Tests/Expected/Fonts/default-context-defaults.swift)
+
+## Usage example
+
+```swift
+// You can create fonts with the convenience constructor like this:
+let displayRegular = UIFont(FontFamily.SFNSDisplay.Regular, size: 20.0)
+let dingbats = UIFont(FontFamily.ZapfDingbats.Regular, size: 20.0)
+
+// Or as an alternative, you can refer to enum instance and call .font on it:
+let sameDisplayRegular = FontFamily.SFNSDisplay.Regular.font(20.0)
+let sameDingbats = FontFamily.ZapfDingbats.Regular.font(20.0)
+```

Documentation/fonts/swift3.md

@@ -0,0 +1,49 @@
+## Template Information
+
+| Name      | Description       |
+| --------- | ----------------- |
+| File name | fonts-swift3.stencil |
+| Invocation example | `swiftgen fonts -t swift3 …` |
+| Language | Swift 3 |
+| Author | Olivier Halligon |
+
+## When to use it
+
+- When you need to generate *Swift 3* code
+
+## Customization
+
+You can customize some elements of this template by overriding the following parameters when invoking `swiftgen` in the command line, using `--param <paramName> <newValue>`
+
+| Parameter Name | Default Value | Description |
+| -------------- | ------------- | ----------- |
+| `enumName` | `FontFamily` | Allows you to change the name of the generated `enum` containing all font families. |
+
+## Generated Code
+
+**Extract:**
+
+```swift
+enum FontFamily {
+  enum SFNSDisplay: String, FontConvertible {
+    case regular = ".SFNSDisplay-Regular"
+  }
+  enum ZapfDingbats: String, FontConvertible {
+    case regular = "ZapfDingbatsITC"
+  }
+}
+```
+
+[Full generated code](https://github.com/SwiftGen/templates/blob/master/Tests/Expected/Fonts/swift3-context-defaults.swift)
+
+## Usage example
+
+```swift
+// You can create fonts with the convenience constructor like this:
+let displayRegular = UIFont(font: FontFamily.SFNSDisplay.regular, size: 20.0)
+let dingbats = UIFont(font: FontFamily.ZapfDingbats.regular, size: 20.0)
+
+// Or as an alternative, you can refer to enum instance and call .font on it:
+let sameDisplayRegular = FontFamily.SFNSDisplay.regular.font(size: 20.0)
+let sameDingbats = FontFamily.ZapfDingbats.regular.font(size: 20.0)
+```

Documentation/images/dot-syntax-swift3.md

@@ -0,0 +1,50 @@
+## Template Information
+
+| Name      | Description       |
+| --------- | ----------------- |
+| File name | images-dot-syntax-swift3.stencil |
+| Invocation example | `swiftgen images -t dot-syntax-swift3 …` |
+| Language | Swift 3 |
+| Author | Olivier Halligon |
+
+## When to use it
+
+- When you need to generate *Swift 3* code
+
+It also takes into account any namespacing folder in your Assets Catalogs (i.e. if you create a folder in your Assets Catalog, select it, and check the "Provides Namespace" checkbox on the Attributes Inspector panel on the right)
+
+## Customization
+
+You can customize some elements of this template by overriding the following parameters when invoking `swiftgen` in the command line, using `--param <paramName> <newValue>`
+
+| Parameter Name | Default Value | Description |
+| -------------- | ------------- | ----------- |
+| `enumName` | `Asset` | Allows you to change the name of the generated `enum` containing all image names. |
+
+## Generated Code
+
+**Extract:**
+
+```swift
+enum Asset {
+  enum Exotic {
+    static let banana: AssetType = "Exotic/Banana"
+    static let mango: AssetType = "Exotic/Mango"
+  }
+  static let `private`: AssetType = "private"
+}
+```
+
+[Full generated code](https://github.com/SwiftGen/templates/blob/master/Tests/Expected/Images/dot-syntax-swift3-context-defaults.swift)
+
+## Usage example
+
+```swift
+// You can create new images with the convenience constructor like this:
+let bananaImage = UIImage(asset: Asset.Exotic.banana)
+let privateImage = UIImage(asset: Asset.private)
+
+// Or as an alternative, you can refer to enum instance and call .image on it:
+let sameBananaImage = Asset.Exotic.banana.image
+let samePrivateImage = Asset.private.image
+```

Documentation/images/dot-syntax.md

@@ -0,0 +1,50 @@
+## Template Information
+
+| Name      | Description       |
+| --------- | ----------------- |
+| File name | images-dot-syntax.stencil |
+| Invocation example | `swiftgen images -t dot-syntax …` |
+| Language | Swift 2 |
+| Author | Olivier Halligon |
+
+## When to use it
+
+- When you need to generate *Swift 2* code
+
+It also takes into account any namespacing folder in your Assets Catalogs (i.e. if you create a folder in your Assets Catalog, select it, and check the "Provides Namespace" checkbox on the Attributes Inspector panel on the right)
+
+## Customization
+
+You can customize some elements of this template by overriding the following parameters when invoking `swiftgen` in the command line, using `--param <paramName> <newValue>`
+
+| Parameter Name | Default Value | Description |
+| -------------- | ------------- | ----------- |
+| `enumName` | `Asset` | Allows you to change the name of the generated `enum` containing all image names. |
+
+## Generated Code
+
+**Extract:**
+
+```swift
+enum Asset {
+  enum Exotic {
+    static let Banana: AssetType = "Exotic/Banana"
+    static let Mango: AssetType = "Exotic/Mango"
+  }
+  static let Private: AssetType = "private"
+}
+```
+
+[Full generated code](https://github.com/SwiftGen/templates/blob/master/Tests/Expected/Images/dot-syntax-context-defaults.swift)
+
+## Usage example
+
+```swift
+// You can create new images with the convenience constructor like this:
+let bananaImage = UIImage(Asset.Exotic.Banana)
+let privateImage = UIImage(Asset.Private)
+
+// Or as an alternative, you can refer to enum instance and call .image on it:
+let sameBananaImage = Asset.Exotic.Banana.image
+let samePrivateImage = Asset.Private.image
+```