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

Authoring guidelines

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.

Style and Formatting

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

Structural guidelines

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: <!--fabric:start-text-->

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, <!--/ and /--> 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.

Sample source file:

/*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 <UIKit/UIKit.h>
/*fabric:start-highlight*/
#import <MoPub/MPAdView.h>
/*fabric:end-highlight*/

@interface ViewController : UIViewController /*fabric:start-highlight*/<MPAdViewDelegate>/*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.

Tips

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