[FeatureHighlight] Split the documentation into separate articles and…

… run the readme generator. (#3620)
material-components · May 1, 2018 · c1fc4e7 · c1fc4e7
1 parent e9923dd
commit c1fc4e7
Show file tree

Hide file tree

Showing 4 changed files with 227 additions and 21 deletions.
diff --git a/components/FeatureHighlight/.vars b/components/FeatureHighlight/.vars
@@ -6,3 +6,4 @@ icon_id=feature_highlight
 color_themer_api=MDCFeatureHighlightColorThemer
 typography_themer_api=MDCFeatureHighlightTypographyThemer
 themer_parameter_name=FeatureHighlightViewController
+short_description=Feature Highlight highlights a part of the screen in order to introduce users to new features and functionality.
diff --git a/components/FeatureHighlight/README.md b/components/FeatureHighlight/README.md
@@ -1,12 +1,15 @@
 <!--docs:
-title: "Feature Highlights"
+title: "Feature Highlight"
 layout: detail
 section: components
 excerpt: "Feature Highlight highlights a part of the screen in order to introduce users to new features and functionality."
 iconId: feature_highlight
 path: /catalog/feature-highlights/
+api_doc_root: true
 -->
 
+<!-- This file was auto-generated using ./scripts/generate_readme FeatureHighlight -->
+
 # Feature Highlight
 
 <div class="article__asset article__asset--screenshot">
@@ -15,50 +18,49 @@ path: /catalog/feature-highlights/
 
 The Feature Highlight component is a way to visually highlight a part of the screen in order to introduce users to new features and functionality.
 
-## Design & API Documentation
+## Design & API documentation
 
 <ul class="icon-list">
-  <li class="icon-list-item icon-list-item--spec"><a href="https://material.io/guidelines/growth-communications/feature-discovery.html">Material Design guidelines: Feature Discovery</a></li>
+  <li class="icon-list-item icon-list-item--link"><a href="https://material.io/guidelines/growth-communications/feature-discovery.html">Material Design guidelines: Feature Discovery</a></li>
 </ul>
 
-## Extensions
+## Table of contents
 
-<ul class="icon-list">
-  <li class="icon-list-item icon-list-item--link"><a href="docs/color-theming.md">Color Theming</a></li>
-  <li class="icon-list-item icon-list-item--link"><a href="docs/typography-theming.md">Typography Theming</a></li>
-</ul>
+- [Installation](#installation)
+  - [Installation with CocoaPods](#installation-with-cocoapods)
+  - [Importing](#importing)
+- [Usage](#usage)
+  - [Typical use: highlight a view](#typical-use-highlight-a-view)
+- [Extensions](#extensions)
+# [Feature Highlight Color Theming](#feature-highlight-color-theming)
+- [Example code](#example-code)
+# [Feature Highlight Typography Theming](#feature-highlight-typography-theming)
+- [Example code](#example-code)
 
 - - -
 
 ## Installation
 
+<!-- Extracted from docs/../../../docs/component-installation.md -->
+
 ### Installation with CocoaPods
 
-To add this component to your Xcode project using CocoaPods, add the following to your `Podfile`:
+Add the following to your `Podfile`:
 
-```
+```bash
 pod 'MaterialComponents/FeatureHighlight'
 ```
 <!--{: .code-renderer.code-renderer--install }-->
 
-To add this component along with its themer and other related extensions, please add the following instead:
-```bash
-pod 'MaterialComponents/FeatureHighlight+Extensions'
-```
-
 Then, run the following command:
 
 ```bash
 pod install
 ```
 
-- - -
-
-## Usage
-
 ### Importing
 
-Before using Feature Highlight, you'll need to import it:
+To import the component:
 
 <!--<div class="material-code-render" markdown="1">-->
 #### Swift
@@ -67,12 +69,18 @@ import MaterialComponents.MaterialFeatureHighlight
 ```
 
 #### Objective-C
+
 ```objc
 #import "MaterialFeatureHighlight.h"
 ```
 <!--</div>-->
 
-### Highlighting a view
+
+## Usage
+
+<!-- Extracted from docs/typical-use-highlight-a-view.md -->
+
+### Typical use: highlight a view
 
 <!--<div class="material-code-render" markdown="1">-->
 #### Swift
@@ -135,3 +143,109 @@ MDCFeatureHighlightViewController *highlightController =
                                                         completion:completion];
 ```
 <!--</div>-->
+
+
+## Extensions
+
+<!-- Extracted from docs/color-theming.md -->
+
+<!--docs:
+title: "Color Theming"
+layout: detail
+section: components
+excerpt: "How to theme Feature Highlight using the Material Design color system."
+iconId: feature_highlight
+path: /catalog/feature-highlights/color-theming/
+-->
+
+# Feature Highlight Color Theming
+
+You can theme feature highlight with your app's color scheme using the ColorThemer extension.
+
+You must first add the Color Themer extension to your project:
+
+```bash
+pod 'MaterialComponents/FeatureHighlight+Extensions/ColorThemer'
+```
+
+## Example code
+
+<!--<div class="material-code-render" markdown="1">-->
+#### Swift
+```swift
+// Step 1: Import the ColorThemer extension
+import MaterialComponents.MaterialFeatureHighlight_ColorThemer
+
+// Step 2: Create or get a color scheme
+let colorScheme = MDCSemanticColorScheme()
+
+// Step 3: Apply the color scheme to your component
+MDCFeatureHighlightColorThemer.applySemanticColorScheme(colorScheme, to: component)
+```
+
+#### Objective-C
+
+```objc
+// Step 1: Import the ColorThemer extension
+#import "MaterialFeatureHighlight+ColorThemer.h"
+
+// Step 2: Create or get a color scheme
+id<MDCColorScheming> colorScheme = [[MDCSemanticColorScheme alloc] init];
+
+// Step 3: Apply the color scheme to your component
+[MDCFeatureHighlightColorThemer applySemanticColorScheme:colorScheme
+     toFeatureHighlightViewController:component];
+```
+<!--</div>-->
+
+<!-- Extracted from docs/typography-theming.md -->
+
+<!--docs:
+title: "Typography Theming"
+layout: detail
+section: components
+excerpt: "How to theme Feature Highlight using the Material Design typography system."
+iconId: feature_highlight
+path: /catalog/feature-highlights/typography-theming/
+-->
+
+# Feature Highlight Typography Theming
+
+You can theme feature highlight with your app's typography scheme using the TypographyThemer extension.
+
+You must first add the Typography Themer extension to your project:
+
+```bash
+pod 'MaterialComponents/FeatureHighlight+Extensions/TypographyThemer'
+```
+
+## Example code
+
+<!--<div class="material-code-render" markdown="1">-->
+#### Swift
+```swift
+// Step 1: Import the TypographyThemer extension
+import MaterialComponents.MaterialFeatureHighlight_TypographyThemer
+
+// Step 2: Create or get a typography scheme
+let typographyScheme = MDCTypographyScheme()
+
+// Step 3: Apply the typography scheme to your component
+MDCFeatureHighlightTypographyThemer.applyTypographyScheme(typographyScheme, to: component)
+```
+
+#### Objective-C
+
+```objc
+// Step 1: Import the TypographyThemer extension
+#import "MaterialFeatureHighlight+TypographyThemer.h"
+
+// Step 2: Create or get a typography scheme
+id<MDCTypographyScheming> typographyScheme = [[MDCTypographyScheme alloc] init];
+
+// Step 3: Apply the typography scheme to your component
+[MDCFeatureHighlightTypographyThemer applyTypographyScheme:colorScheme
+     toFeatureHighlightViewController:component];
+```
+<!--</div>-->
+
diff --git a/components/FeatureHighlight/docs/README.md b/components/FeatureHighlight/docs/README.md
@@ -0,0 +1,28 @@
+# Feature Highlight
+
+<div class="article__asset article__asset--screenshot">
+  <img src="docs/assets/feature_highlight.png" alt="Feature Highlight" width="375">
+</div>
+
+The Feature Highlight component is a way to visually highlight a part of the screen in order to introduce users to new features and functionality.
+
+## Design & API documentation
+
+* [Material Design guidelines: Feature Discovery](https://material.io/guidelines/growth-communications/feature-discovery.html)
+
+<!-- toc -->
+
+- - -
+
+## Installation
+
+- [Typical installation](../../../docs/component-installation.md)
+
+## Usage
+
+- [Typical use: highlight a view](typical-use-highlight-a-view.md)
+
+## Extensions
+
+- [Color Theming](color-theming.md)
+- [Typography Theming](typography-theming.md)
diff --git a/components/FeatureHighlight/docs/typical-use-highlight-a-view.md b/components/FeatureHighlight/docs/typical-use-highlight-a-view.md
@@ -0,0 +1,63 @@
+### Typical use: highlight a view
+
+<!--<div class="material-code-render" markdown="1">-->
+#### Swift
+```swift
+let completion = {(accepted: Bool) in
+  // perform analytics here
+  // and record whether the highlight was accepted
+}
+
+let highlightController = MDCFeatureHighlightViewController(highlightedView: viewToHighlight,
+                                                            completion: completion)
+highlightController.titleText = "Just how you want it"
+highlightController.bodyText = "Tap the menu button to switch accounts, change settings & more."
+highlightController.outerHighlightColor =
+  UIColor.blue.withAlphaComponent(kMDCFeatureHighlightOuterHighlightAlpha)
+present(highlightController, animated: true, completion:nil)
+```
+
+#### Objective-C
+```objc
+MDCFeatureHighlightCompletion completion = ^(BOOL accepted) {
+  // perform analytics here
+  // and record whether the highlight was accepted
+};
+
+MDCFeatureHighlightViewController *highlightController =
+[[MDCFeatureHighlightViewController alloc] initWithHighlightedView:viewToHighlight
+                                                        completion:completion];
+highlightController.titleText = @"Just how you want it";
+highlightController.bodyText = @"Tap the menu button to switch accounts, change settings & more.";
+highlightController.outerHighlightColor =
+    [[UIColor blueColor] colorWithAlphaComponent:kMDCFeatureHighlightOuterHighlightAlpha];
+[self presentViewController:highlightController animated:YES completion:nil];
+```
+<!--</div>-->
+
+Often when highlighting a view you will want to display a different view to the one you are highlighting. For example, flipping the primary and secondary colors in the presented version.
+
+<!--<div class="material-code-render" markdown="1">-->
+#### Swift
+```swift
+let displayedButton = UIButton(type: .system)
+displayedButton.setTitle(highlightedButton.title(for: .normal), for: .normal)
+displayedButton.setTitleColor(highlightedButton.backgroundColor, for: .normal)
+displayedButton.backgroundColor = highlightedButton.titleColor(for: .normal)
+
+let highlightController = MDCFeatureHighlightViewController(highlightedView: highlightedButton, andShow: displayedButton, completion: completion)
+```
+
+#### Objective-C
+```objc
+UIButton *displayedButton = [UIButton buttonWithType:UIButtonTypeSystem];
+[displayedButton setTitle:[highlightedButton titleForState:UIControlStateNormal]
+                 forState:UIControlStateNormal];
+[displayedButton setTitleColor:highlightedButton.backgroundColor forState:UIControlStateNormal];
+displayedButton.backgroundColor = [highlightedButton titleColorForState:UIControlStateNormal];
+MDCFeatureHighlightViewController *highlightController =
+[[MDCFeatureHighlightViewController alloc] initWithHighlightedView:highlightedButton
+                                                       andShowView:displayedButton
+                                                        completion:completion];
+```
+<!--</div>-->