[Snackbar] Split the documentation into separate articles and run the…

… readme generator. (#3627)

components/Snackbar/.vars

@@ -5,3 +5,4 @@ root_path=/catalog/snackbars
 icon_id=toast
 color_themer_api=MDCSnackbarColorThemer
 typography_themer_api=MDCSnackbarTypographyThemer
+short_description=Snackbars provide brief feedback about an operation through a message at the bottom of the screen.

components/Snackbar/README.md

@@ -1,12 +1,15 @@
 <!--docs:
-title: "Snackbars"
+title: "Snackbar"
 layout: detail
 section: components
 excerpt: "Snackbars provide brief feedback about an operation through a message at the bottom of the screen."
 iconId: toast
 path: /catalog/snackbars/
+api_doc_root: true
 -->
 
+<!-- This file was auto-generated using ./scripts/generate_readme Snackbar -->
+
 # Snackbar
 
 <div class="article__asset article__asset--screenshot">
@@ -17,37 +20,32 @@ Snackbars provide brief feedback about an operation through a message at the bot
 Snackbars contain up to two lines of text directly related to the operation performed. They may
 contain a text action, but no icons.
 
-## Design & API Documentation
+## Design & API documentation
 
 <ul class="icon-list">
   <li class="icon-list-item icon-list-item--spec"><a href="https://material.io/go/design-snackbars">Material Design guidelines: Snackbars</a></li>
 </ul>
 
-## Extensions
+## Related components
 
 <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>
+  <li class="icon-list-item icon-list-item--link"><a href="../OverlayWindow">OverlayWindow</a></li>
 </ul>
 
-- - -
-
-## Installation
-
-### Installation with CocoaPods
-
-To add this component to your Xcode project using CocoaPods, add the following to your `Podfile`:
-
-```
-pod 'MaterialComponents/Snackbar'
-```
-<!--{: .code-renderer.code-renderer--install }-->
-
-Then, run the following command:
-
-```bash
-pod install
-```
+## Table of contents
+
+- [Overview](#overview)
+  - [Snackbar Manager and Message](#snackbar-manager-and-message)
+  - [Suspending and Resuming Display of Messages](#suspending-and-resuming-display-of-messages)
+- [Installation](#installation)
+  - [Installation with CocoaPods](#installation-with-cocoapods)
+  - [Importing](#importing)
+- [Usage](#usage)
+  - [Typical use: display a message](#typical-use-display-a-message)
+  - [Typical use: display a message with an action](#typical-use-display-a-message-with-an-action)
+- [Extensions](#extensions)
+  - [Color Theming](#color-theming)
+  - [Typography Theming](#typography-theming)
 
 - - -
 
@@ -66,19 +64,28 @@ messages are suspended the manager provides a suspension token that the client m
 messages are suspended. When the client releases the suspension token or calls the manager's resume
 method with the suspension token, then messages will resume being displayed.
 
-- - -
+## Installation
 
-## Usage
+<!-- Extracted from docs/../../../docs/component-installation.md -->
 
-Displaying a snackbar requires using two classes: MDCSnackbarManager and MDCSnackbarMessage.
-First, create an instance of MDCSnackbarMessage and provide a string to display to the user. Next,
-pass the MDCSnackbarMessage to the MDCSnackbarManager with the static showMessage method. This will
-automatically construct an MDCSnackbarMessageView and appropriate overlay views so the snackbar is
-visible to the user.
+### Installation with CocoaPods
+
+Add the following to your `Podfile`:
+
+```bash
+pod 'MaterialComponents/Snackbar'
+```
+<!--{: .code-renderer.code-renderer--install }-->
+
+Then, run the following command:
+
+```bash
+pod install
+```
 
 ### Importing
 
-Before using Snackbar, you'll need to import it:
+To import the component:
 
 <!--<div class="material-code-render" markdown="1">-->
 #### Swift
@@ -87,16 +94,24 @@ import MaterialComponents.MaterialSnackbar
 ```
 
 #### Objective-C
+
 ```objc
 #import "MaterialSnackbar.h"
 ```
 <!--</div>-->
 
-- - -
 
-## Examples
+## Usage
+
+Displaying a snackbar requires using two classes: MDCSnackbarManager and MDCSnackbarMessage.
+First, create an instance of MDCSnackbarMessage and provide a string to display to the user. Next,
+pass the MDCSnackbarMessage to the MDCSnackbarManager with the static showMessage method. This will
+automatically construct an MDCSnackbarMessageView and appropriate overlay views so the snackbar is
+visible to the user.
+
+<!-- Extracted from docs/typical-use-display-a-message.md -->
 
-### Display a Snackbar Message
+### Typical use: display a message
 
 <!--<div class="material-code-render" markdown="1">-->
 #### Swift
@@ -116,7 +131,9 @@ message.text = @"How much wood would a woodchuck chuck if a woodchuck could chuc
 ```
 <!--</div>-->
 
-### Display a Snackbar Message with an Action
+<!-- Extracted from docs/typical-use-display-a-message-with-action.md -->
+
+### Typical use: display a message with an action
 
 <!--<div class="material-code-render" markdown="1">-->
 #### Swift
@@ -148,10 +165,84 @@ message.action = action;
 ```
 <!--</div>-->
 
-- - -
 
-## Related Components
+## Extensions
+
+<!-- Extracted from docs/color-theming.md -->
+
+### Color Theming
+
+You can theme an snackbar with your app's color scheme using the ColorThemer extension.
+
+You must first add the Color Themer extension to your project:
+
+```bash
+pod 'MaterialComponents/Snackbar+Extensions/ColorThemer'
+```
+
+<!--<div class="material-code-render" markdown="1">-->
+#### Swift
+```swift
+// Step 1: Import the ColorThemer extension
+import MaterialComponents.MaterialSnackbar_ColorThemer
+
+// Step 2: Create or get a color scheme
+let colorScheme = MDCSemanticColorScheme()
+
+// Step 3: Apply the color scheme to your component
+MDCSnackbarColorThemer.applySemanticColorScheme(colorScheme)
+```
+
+#### Objective-C
+
+```objc
+// Step 1: Import the ColorThemer extension
+#import "MaterialSnackbar+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
+[MDCSnackbarColorThemer applySemanticColorScheme:colorScheme];
+```
+<!--</div>-->
+
+<!-- Extracted from docs/typography-theming.md -->
+
+### Typography Theming
+
+You can theme an snackbar with your app's typography scheme using the TypographyThemer extension.
+
+You must first add the Typography Themer extension to your project:
+
+```bash
+pod 'MaterialComponents/Snackbar+Extensions/TypographyThemer'
+```
+
+<!--<div class="material-code-render" markdown="1">-->
+#### Swift
+```swift
+// Step 1: Import the TypographyThemer extension
+import MaterialComponents.MaterialSnackbar_TypographyThemer
+
+// Step 2: Create or get a typography scheme
+let typographyScheme = MDCTypographyScheme()
+
+// Step 3: Apply the typography scheme to your component
+MDCSnackbarTypographyThemer.applyTypographyScheme(typographyScheme)
+```
+
+#### Objective-C
+
+```objc
+// Step 1: Import the TypographyThemer extension
+#import "MaterialSnackbar+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
+[MDCSnackbarTypographyThemer applyTypographyScheme:colorScheme];
+```
+<!--</div>-->
 
-<ul class="icon-list">
-  <li class="icon-list-item icon-list-item--components"><a href="../OverlayWindow">Overlay Windows</a></li>
-</ul>

components/Snackbar/docs/README.md

@@ -0,0 +1,56 @@
+# Snackbar
+
+<div class="article__asset article__asset--screenshot">
+  <img src="docs/assets/snackbar.png" alt="Snackbar" width="375">
+</div>
+
+Snackbars provide brief feedback about an operation through a message at the bottom of the screen.
+Snackbars contain up to two lines of text directly related to the operation performed. They may
+contain a text action, but no icons.
+
+## Design & API documentation
+
+* [Material Design guidelines: Snackbars](https://material.io/go/design-snackbars)
+
+## Related components
+
+* [OverlayWindow](../../OverlayWindow)
+
+<!-- toc -->
+
+- - -
+
+## Overview
+
+### Snackbar Manager and Message
+
+Snackbar is comprised of two classes: MDCSnackbarManager and MDCSnackbarMessage. Snackbar messages
+contain text to be displayed to a user. Messages are passed to the manager. The manager decides when
+it is appropriate to show a message to the user.
+
+### Suspending and Resuming Display of Messages
+
+Snackbar manager can be instructed to suspend and resume displaying messages as needed. When
+messages are suspended the manager provides a suspension token that the client must keep as long as
+messages are suspended. When the client releases the suspension token or calls the manager's resume
+method with the suspension token, then messages will resume being displayed.
+
+## Installation
+
+- [Typical installation](../../../docs/component-installation.md)
+
+## Usage
+
+Displaying a snackbar requires using two classes: MDCSnackbarManager and MDCSnackbarMessage.
+First, create an instance of MDCSnackbarMessage and provide a string to display to the user. Next,
+pass the MDCSnackbarMessage to the MDCSnackbarManager with the static showMessage method. This will
+automatically construct an MDCSnackbarMessageView and appropriate overlay views so the snackbar is
+visible to the user.
+
+- [Typical use: display a message](typical-use-display-a-message.md)
+- [Typical use: display a message with an action](typical-use-display-a-message-with-action.md)
+
+## Extensions
+
+- [Color Theming](color-theming.md)
+- [Typography Theming](typography-theming.md)

components/Snackbar/docs/color-theming.md

@@ -1,13 +1,4 @@
-<!--docs:
-title: "Color Theming"
-layout: detail
-section: components
-excerpt: "How to theme Snackbar using the Material Design color system."
-iconId: toast
-path: /catalog/snackbars/color-theming/
--->
-
-# Snackbar Color Theming
+### Color Theming
 
 You can theme an snackbar with your app's color scheme using the ColorThemer extension.
 
@@ -17,8 +8,6 @@ You must first add the Color Themer extension to your project:
 pod 'MaterialComponents/Snackbar+Extensions/ColorThemer'
 ```
 
-## Example code
-
 <!--<div class="material-code-render" markdown="1">-->
 #### Swift
 ```swift

components/Snackbar/docs/typical-use-display-a-message-with-action.md

@@ -0,0 +1,31 @@
+### Typical use: display a message with an action
+
+<!--<div class="material-code-render" markdown="1">-->
+#### Swift
+
+```swift
+let action = MDCSnackbarMessageAction()
+let actionHandler = {() in
+  let answerMessage = MDCSnackbarMessage()
+  answerMessage.text = "Fascinating"
+  MDCSnackbarManager.show(answerMessage)
+}
+action.handler = actionHandler
+action.title = "OK"
+message.action = action
+```
+
+#### Objective-C
+
+```objc
+MDCSnackbarMessageAction *action = [[MDCSnackbarMessageAction alloc] init];
+void (^actionHandler)() = ^() {
+  MDCSnackbarMessage *answerMessage = [[MDCSnackbarMessage alloc] init];
+  answerMessage.text = @"A lot";
+  [MDCSnackbarManager showMessage:answerMessage];
+};
+action.handler = actionHandler;
+action.title = @"Answer";
+message.action = action;
+```
+<!--</div>-->

components/Snackbar/docs/typical-use-display-a-message.md

@@ -0,0 +1,19 @@
+### Typical use: display a message
+
+<!--<div class="material-code-render" markdown="1">-->
+#### Swift
+
+```swift
+let message = MDCSnackbarMessage()
+message.text = "The groundhog (Marmota monax) is also known as a woodchuck or whistlepig."
+MDCSnackbarManager.show(message)
+```
+
+#### Objective-C
+
+```objc
+MDCSnackbarMessage *message = [[MDCSnackbarMessage alloc] init];
+message.text = @"How much wood would a woodchuck chuck if a woodchuck could chuck wood?";
+[MDCSnackbarManager showMessage:message];
+```
+<!--</div>-->

components/Snackbar/docs/typography-theming.md

@@ -1,13 +1,4 @@
-<!--docs:
-title: "Typography Theming"
-layout: detail
-section: components
-excerpt: "How to theme Snackbar using the Material Design typography system."
-iconId: toast
-path: /catalog/snackbars/typography-theming/
--->
-
-# Snackbar Typography Theming
+### Typography Theming
 
 You can theme an snackbar with your app's typography scheme using the TypographyThemer extension.
 
@@ -17,8 +8,6 @@ You must first add the Typography Themer extension to your project:
 pod 'MaterialComponents/Snackbar+Extensions/TypographyThemer'
 ```
 
-## Example code
-
 <!--<div class="material-code-render" markdown="1">-->
 #### Swift
 ```swift