kft-parser

kft-parser is a local tool for previewing and processing the “Code Examples” tutorials in
the Fabric Mac app and Android plugins.

Kit Feature Tutorials are built by taking a functioning demo project and annotating its source
files with special comments. kft-parser extracts the content from these files to build tutorials
that have text descriptions and code samples with highlighted “click-to-copy” blocks.

Using kft-parser

#### Installation
``
$ npm install kft-parser
`

#### Running
`
$ kft-parser path/to/features.json
`

This will create a build/kfts directory with an HTML preview of each KFT in the features.json
manifest file. You can open these previews with your web browser to see how your KFT content will
be rendered.

kft-parser will also create an upload.json file that can be uploaded to Fabric as part of a
kit release.

Building a KFT

$3

All KFTs should start from sample projects that demonstate one or more features of an SDK. **Running
the project should show the feature in action, with a clear, verifiable output.** This output may
be the purpose of the kit itself (such as a Tweet or map) or an alert or toast that proves an
action was successful (like a login or credit card transaction).

The goal of a Kit Feature Tutorial is to give a developer a concrete starting point with your
SDK. At the end of a KFT, a developer should be able to see your kit doing something useful for
them.

KFTs should aim to be short and easy to follow: not very many lines of code, few blocks to add
per file, and not very many files (one is best, four is probably too many).

Adding the highlighted code to an appropriate file must leave the developer's app in a compilable,
working state (an exception is Java imports, which should be included in the code block for
reference but need not be highlighted, as the developer will likely use the IDE to resolve them).

Nevertheless, *a KFT should show a complete, correct* use of an SDK feature, demonstrating any
necessary reliability or cleanup requirements**.

In cases that there is a change the developer should make later (e.g a hardcoded ID or credential)
add a // TODO: annotation that makes it clear that the developer should change something.

A KFT should be set up so that the developer can see how to modify it to meet their needs.
For example, a TwitterKit KFT uses a sample Tweet ID when rendering a Tweet view so that the
developer can see the UI working, but it’s trivial to see how to provide one’s own Tweet ID. In
the Digits KFT, an alert dialog with the user’s phone number is shown on successful login. The
developer can therefore see login working, and it's clear where the hook is to integrate Digits
with their user system.

$3

KFTs are declaritive, not suggestive.

`
Good: Add a "Force Crash" button…
Bad: You can add a "Force Crash" button…
`

Each KFT step should succinclty describe the context the developer needs to determine where to insert it:

`
Good: Add this code to a layout where you'd like the button to appear.
Bad (not enough context): Add this code
Bad (too much text, forces code below the fold): Add this display code to a layout which will host the "Force Crash" button, which, when clicked will cause the application to crash.
`

Because display space is limited, please also adhere to these formatting guidelines:

* Set indent width to 2 spaces for Java (no tabs)
* Wrap comments at 70 characters
* Try to wrap code at 70 characters
Use imports in Java to reduce the import statements

$3

Each step should typically correspond to one file that the developer must modify. In the case of
Objective-C, group .h and .m files together.

#### Last step

The last step of any KFT should be titled “Try it out!” and be a Markdown file that covers the following 3 points:

* What the developer should do to see the feature working, and what they’re expected to find.

* Troubleshooting hints in case the above is not happening (phased as the answer to a question, e.g "Not seeing the crash?").

* What the next steps are, such as API documentation for further UI customization or instructions
to visit a web dashboard to set up an aspect of the feature.

The last step should generally start with "Run your app" along with any actions they need to take after launching the app.

Syntax

All KFT annotations are fabric: followed by a start- or end- command. These are enclosed
completely in a language's block comment syntax:

Objective-C, Swift, Java, &tc.: /fabric:start-text*/
XML*:

If an annotation is on a line by itself, the line is not included in the output at all (important
for not introducing blank lines in code samples). Annotations can also be intermixed with code
on the same line.

start-text / end-text:

Define chunks of Markdown (parsed with CommonMark libraries) that will be
included in the output. Multiple text blocks within a file will be concatenated and all included at the top.

In C-like languages, leading // s will be stripped from lines so that your text can be a source
comment.

In XML, will be stripped from lines. (Note the /s: they’re important because
kft-parser is a hack.)

start-code / end-code:

Define the code that will be shown in the step. Multiple code blocks will be concatenated
together without separation. Spaces are recommended for indentation for consistency.

start-hide / end-hide:

Keeps the code within from appearing in a code block. Use this around code that is necessary to
build and run the sample app but is either private (like API keys) or generally uninteresting
(boilerplate that's not relevant to the feature).

Not legal in a text block. Can be used within a highlight block.

start-highlight / end-highlight

Marks an area of code to be highlighted. When the developer clicks on the code in the plugin, it
will be copied to the clipboard.

Not legal in a text block or in a hide block. Can include hide blocks to limit what’s shown and
copied.

start-strikethrough / end-strikethrough

Used to mark code that should be removed.
Adds a strikethough to the text between the start & end annotations.
~~like this!~~

Only legal in a code block.

Leading comment characters (e.g. "//") will be stripped, allowing strikethrough code to be ignored when building the project.

###Sample features.json
Features.json describes the metadata about the features, their title, their source locations, etc.

The titles should be _"Title Cased"_, and the descriptions should be full sentences (with periods).

`
[
{
"name": "Feature Name",
"description": "Feature Description",
"steps": [
{
"title": "Step Title",
"source": {
"objc": "relative/path/to/AppDelegate.m",
"swift": "relative/path/to/AppDelegate.swift"
}
},
{
"title": "Second Step Title",
"source": {
"objc": [
"relative/path/to/ViewController.h",
"relative/path/to/ViewController.m"
],
"swift": "relative/path/to/ViewController.swift"
}
},
{
"title": "Try it out!",
"source": "text/Feature Last Step.md"
}
]
}
}
]
`

Note that both source and title keys are required.

source can contain a string path, an array of string paths, or a hash of either strings or string
paths, keyed on the language.




$3


`
/fabric:start-text/
// An MPAdView is a fixed-size view that you can construct in your view controller's
// viewDidLoad method and add to its view.
//
// You'll need to implement the MPAdViewDelegate protocol in your view controller so that the ad
// can present a modal view when it's tapped.
/fabric:end-text/
//
//
// ViewController.h
// MoPubBannerFeature
//
// Created by Joan Smith on 7/23/15.
// Copyright (c) 2015 Twitter, Inc. All rights reserved.
//

/fabric:start-code/
#import
/fabric:start-highlight/
#import
/fabric:end-highlight/

@interface ViewController : UIViewController /fabric:start-highlight//fabric:end-highlight/

/fabric:start-highlight/
@property (nonatomic, retain) MPAdView *adView;
/fabric:end-highlight/

@end
/fabric:end-code/
`

#### Referencing API keys on android:

On Android, API keys for your kit will be injected into the app’s strings.xml.

Let’s say your key is named com.kit.live.api_key (See our key-provisioning documentation for naming
conventions.) Within your KFT, you can reference your key by replacing all periods and hyphens with underscores:

`
getString(R.string.com_kit_live_api_key)
`

This works from a method of an Activity because Activity implements Context. If your code
example is not for an Activity, you would need to call getString on a Context object.

$3

When creating a sample project, use a bundle identifier that matches the bundle id of the kit,
plus the name of the feature (if applicable). When necessary, it helps to specify the language.
(e.g. for Crashlytics Kit com.twitter.crashlytics.ios.sample.UserIdentifierFeatureObjC)

Onboard the kit into the project using Fabric so that Fabric.with` statements are present in
initialization code.

Hide or delete boilerplate methods or imports that aren’t relevant to the code sample.

Screenshots

!Objective-C Step 1
!Objective-C Step 2

!Java Step 1
!Java Step 1