Add documentation for each template #2

AliSoftware · 2017-01-04T21:53:21Z

⚠️ WIP ⚠️

AliSoftware · 2017-02-19T22:51:38Z

documentation/images/images-default.md

+This template is the default template used by SwiftGen when parsing images in Asset Catalogs.
+It generates Swift 3 code and is suitable for most needs.
+
+## Customization


We should now actually separate that section to show both --param and ENV possible customizations (maybe in the same section, but find a way to make them both visible anyway)

I think the whole explanation about "customize using --param" and that we load ENV variables, should be in the SwiftGen documentation itself. Here we should only document what is accepted (and in some cases "why"), and link to the swiftgen docs on how to use it.

AliSoftware · 2017-02-19T22:52:36Z

documentation/images/images-default.md

+| Name      | Description       |
+| --------- | ----------------- |
+| File name | images-default.stencil |
+| Invocation example | `swiftgen storyboard -t default …` |


That should b swiftgen images … instead, obviously

AliSoftware · 2017-02-19T22:55:00Z

documentation/images/images-default.md

+## When to use it
+
+This template is the default template used by SwiftGen when parsing images in Asset Catalogs.
+It generates Swift 3 code and is suitable for most needs.


Now that I think of it, when I thought about adding that section at first, is was more to say:

"This template is more suitable for when you name your images with underscores" or "This template is more suitable for when you use that "provides namespace" checkbox on the folders inside your xcasset catalog", and "this template supports multiple catalogs by creating a separate enum for each catalog", stuff like that

Aren't we getting rid of the flat images enum in 5.0? #11

I get the intention though, but think that quite a few recommendations won't be needed once we remove the old stuff. Some options will probably remain, like the flat strings version, and can provide recommendations for those.

Yeah that PR was opened before we even decided to get rid of the "default" behavior even.

Again the idea behind this paragraph, which would be probably more useful for the strings templates especially, is to tell which template to use depending on which banking conventions you have as input (how you name your strings keys for example, are you the kind of people that use all-caps keys, or keys structured with dots or underscore to separate the key parts, etc… and what do you expect as output (structured, not structured…)

Might be less relevant for images template because the naming doesn't impact the structural split (the organisation of the assets catalog does), but you get the idea. Because not everyone has the same naming and organization conventions the aim is to help people choose the right template for them.

AliSoftware · 2017-02-19T22:56:07Z

documentation/images/images-default.md

+<summary>Full generated code</summary>
+
+```swift
+(the full code here)


(or a link to the "expected output" fixture)

As we have the output files for testing, and because they are prone to change, it might be best to just link to them.

For the full code I totally agree.

For the extract it would be nice if we could try to keep it here in that documentation and try to keep it uo to date, because it allows people to see it at a glance.

djbe · 2017-04-17T15:32:23Z

I wanted to work on the documentation today, but am not sure how much worth it is, as we'll be removing quite a few things once we work on 5.0. Do I only document the templates we want to keep for 5.0?

AliSoftware · 2017-04-17T15:41:49Z

I think it's only worth working on documenting templates we intend to keep. No need to document things (templates, tags, filters or anything) that we intend to drop in 5.0

…plate

…lates

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.

AliSoftware · 2017-05-07T21:28:04Z

Documentation/strings/default.md

+## When to use it
+
+- When you need to generate *Swift 2* code
+- If you use unstructured keys for your strings, or a structure that we don't support (yet). If you use "dot-syntax" keys, please check out the [dot-syntax](dot-syntax.md) template.


"unstructured key names"?

AliSoftware · 2017-05-07T21:31:57Z

Documentation/strings/default.md

+
+## Customization
+
+You can customise some elements of this template by overriding the following parameters when invoking `swiftgen` in the command line, using `--param <paramName> <newValue>`


s/customise/customize/, right? (applies on every doc file)

AliSoftware added the status: WIP label Jan 4, 2017

djbe force-pushed the master branch from 4de971b to e2c06fe Compare January 14, 2017 01:33

AliSoftware force-pushed the feature/templates-documentation branch from fceda0a to 3c19f4b Compare February 19, 2017 01:23

AliSoftware force-pushed the master branch from c52ace1 to dc29584 Compare February 19, 2017 02:19

AliSoftware force-pushed the feature/templates-documentation branch from 3c19f4b to 1e18d17 Compare February 19, 2017 02:23

AliSoftware mentioned this pull request Feb 19, 2017

[Documentation] Add detailed description for each template SwiftGen/SwiftGen#232

Closed

AliSoftware commented Feb 19, 2017

View reviewed changes

djbe mentioned this pull request Feb 23, 2017

Storyboards: module name for target may not match "customModule" set by Xcode #25

Closed

djbe force-pushed the feature/templates-documentation branch from 1e18d17 to fbbedff Compare April 17, 2017 17:08

djbe force-pushed the feature/templates-documentation branch from a46d637 to 8d1999d Compare April 24, 2017 17:28

djbe force-pushed the feature/templates-documentation branch 2 times, most recently from a0aa747 to eaa66b8 Compare May 7, 2017 00:01

djbe removed the status: WIP label May 7, 2017

djbe mentioned this pull request May 7, 2017

SwiftGen 4.2.1 SwiftGen/SwiftGen#286

Closed

18 tasks

djbe added this to the SwiftGen 4.2.1 milestone May 7, 2017

AliSoftware and others added 10 commits May 7, 2017 23:14

template documentation directory structure

fdf2ee5

Initial example of a template documentation: the "images-default" tem…

42412b5

…plate

move

54ceed3

some template documentation. Todo: macOS storyboards and strings temp…

aeac4f6

…lates

small fixes

cdea9b5

storyboards macOS

120d270

correct naming of images doc files

4a42e8e

Strings dot syntax

13e3ee4

colors: clarify small bit compared to rawvalue

b8c70dd

djbe force-pushed the feature/templates-documentation branch from ef345f3 to a076000 Compare May 7, 2017 21:25

AliSoftware commented May 7, 2017

View reviewed changes

document flat string templates

4208973

djbe force-pushed the feature/templates-documentation branch from a076000 to 4208973 Compare May 7, 2017 21:30

AliSoftware commented May 7, 2017

View reviewed changes

AliSoftware self-assigned this May 7, 2017

s/customise/customize/

a4ed553

AliSoftware merged commit 431f2f2 into master May 7, 2017

AliSoftware deleted the feature/templates-documentation branch May 7, 2017 21:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add documentation for each template #2

Add documentation for each template #2

AliSoftware commented Jan 4, 2017 •

edited

Loading

AliSoftware Feb 19, 2017

djbe Apr 17, 2017

AliSoftware Apr 17, 2017

AliSoftware Feb 19, 2017

AliSoftware Feb 19, 2017

djbe Apr 17, 2017

AliSoftware Apr 17, 2017

AliSoftware Feb 19, 2017

djbe Apr 17, 2017

AliSoftware Apr 17, 2017

djbe commented Apr 17, 2017

AliSoftware commented Apr 17, 2017

AliSoftware May 7, 2017

AliSoftware May 7, 2017


		## Customization

		You can customise some elements of this template by overriding the following parameters when invoking `swiftgen` in the command line, using `--param <paramName> <newValue>`

Add documentation for each template #2

Add documentation for each template #2

Conversation

AliSoftware commented Jan 4, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

djbe commented Apr 17, 2017

AliSoftware commented Apr 17, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AliSoftware commented Jan 4, 2017 •

edited

Loading