Rework of "Lay out a widget" + use of code-excerpts

Contributes to #2233

examples/layout/base/README.md

@@ -1 +1 @@
-../../../README.md
+../../README.md

examples/layout/base/lib/main.dart

@@ -2,6 +2,7 @@ import 'package:flutter/material.dart';
 
 void main() => runApp(MyApp());
 
+// #docregion MyApp
 class MyApp extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
@@ -11,9 +12,13 @@ class MyApp extends StatelessWidget {
         appBar: AppBar(
           title: Text('Flutter layout demo'),
         ),
+        // #docregion centered-text
         body: Center(
+          // #docregion text
           child: Text('Hello World'),
+          // #enddocregion text
         ),
+        // #enddocregion centered-text
       ),
     );
   }

examples/layout/lakes/step5/lib/main.dart

@@ -34,10 +34,12 @@ class MyApp extends StatelessWidget {
             ),
           ),
           /*3*/
+          // #docregion Icon
           Icon(
             Icons.star,
             color: Colors.red[500],
           ),
+          // #enddocregion Icon
           Text('41'),
         ],
       ),
@@ -79,12 +81,14 @@ class MyApp extends StatelessWidget {
         ),
         body: Column(
           children: [
+            // #docregion Image-asset
             Image.asset(
               'images/lake.jpg',
               width: 600.0,
               height: 240.0,
               fit: BoxFit.cover,
             ),
+            // #enddocregion Image-asset
             titleSection,
             buttonSection,
             textSection,

examples/layout/non_material/README.md

@@ -0,0 +1 @@
+../../README.md

examples/layout/non_material/lib/main.dart

@@ -0,0 +1,20 @@
+import 'package:flutter/material.dart';
+
+void main() => runApp(MyApp());
+
+// #docregion MyApp
+class MyApp extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return Container(
+      decoration: BoxDecoration(color: Colors.white),
+      child: Center(
+        child: Text(
+          'Hello World',
+          textDirection: TextDirection.ltr,
+          style: TextStyle(fontSize: 32.0, color: Colors.black87),
+        ),
+      ),
+    );
+  }
+}

examples/layout/non_material/pubspec.yaml

@@ -0,0 +1,19 @@
+name: layout
+description: >
+  Sample app from "Building Layouts", https://flutter.io/docs/development/ui/layout.
+version: 1.0.0
+
+environment:
+  sdk: '>=2.0.0-dev.68.0 <3.0.0'
+
+dependencies:
+  flutter:
+    sdk: flutter
+  cupertino_icons: ^0.1.2
+
+dev_dependencies:
+  flutter_test:
+    sdk: flutter
+
+flutter:
+  uses-material-design: true

examples/layout/non_material/test/widget_test.dart

@@ -0,0 +1,12 @@
+// Basic Flutter widget test. Learn more at https://flutter.io/docs/testing.
+
+import 'package:flutter_test/flutter_test.dart';
+
+import 'package:layout/main.dart';
+
+void main() {
+  testWidgets('Codelab smoke test', (WidgetTester tester) async {
+    await tester.pumpWidget(new MyApp());
+    expect(find.text('Hello World'), findsOneWidget);
+  });
+}

src/docs/development/ui/layout/index.md

@@ -107,135 +107,147 @@ It also shows the entire code for a simple Hello World app.
 In Flutter,
 it takes only a few steps to put text, an icon, or an image on the screen.
 
- 1. Select a layout widget to hold the object.
+### 1. Select a layout widget
 
-    Choose from a variety of [layout widgets][] based
-    on how you want to align or constrain the visible widget,
-    as these characteristics are typically passed on to the
-    contained widget.
+Choose from a variety of [layout widgets][] based
+on how you want to align or constrain the visible widget,
+as these characteristics are typically passed on to the
+contained widget.
 
-    This example uses [Center][] which centers its content
-    horizontally and vertically.
+This example uses [Center][] which centers its content
+horizontally and vertically.
 
- 2. Create a widget to hold a visible object.
+### 2. Create a visible widget
 
-    For example, create a [Text][] widget:
+For example, create a [Text][] widget:
 
-    <!-- skip -->
-    {% prettify dart %}
-    Text('Hello World', style: TextStyle(fontSize: 32.0))
-    {% endprettify %}
+<?code-excerpt "layout/base/lib/main.dart (text)" replace="/child: //g"?>
+```dart
+Text('Hello World'),
+```
 
-    Create an [Image][] widget:
+Create an [Image][] widget:
 
-    <!-- skip -->
-    {% prettify dart %}
-    Image.asset('images/myPic.jpg', fit: BoxFit.cover)
-    {% endprettify %}
+<?code-excerpt "layout/lakes/step5/lib/main.dart (Image-asset)" remove="/width|height/"?>
+```dart
+Image.asset(
+  'images/lake.jpg',
+  fit: BoxFit.cover,
+),
+```
 
-    Create an [Icon][] widget:
+Create an [Icon][] widget:
 
-    <!-- skip -->
-    {% prettify dart %}
-    Icon(Icons.star, color: Colors.red[500])
-    {% endprettify %}
+<?code-excerpt "layout/lakes/step5/lib/main.dart (Icon)"?>
+```dart
+Icon(
+  Icons.star,
+  color: Colors.red[500],
+),
+```
 
- 3. Add the visible widget to the layout widget.
+### 3. Add the visible widget to the layout widget
 
-    All layout widgets have either of the following:
+<?code-excerpt path-base="layout/base"?>
 
-    - A `child` property if they take a single child -- for example, `Center` or
-      `Container`
-    - A `children` property if they take a list of widgets -- for example, `Row`,
-      `Column`, `ListView`, or `Stack`.
+All layout widgets have either of the following:
 
-    Add the `Text` widget to the `Center` widget:
+- A `child` property if they take a single child -- for example, `Center` or
+  `Container`
+- A `children` property if they take a list of widgets -- for example, `Row`,
+  `Column`, `ListView`, or `Stack`.
 
-    <!-- skip -->
-    {% prettify dart %}
-    Center(
-      child: Text('Hello World', style: TextStyle(fontSize: 32.0))
-    {% endprettify %}
+Add the `Text` widget to the `Center` widget:
 
- 4. Add the layout widget to the page.
+<?code-excerpt "lib/main.dart (centered-text)" replace="/body: //g"?>
+```dart
+Center(
+  child: Text('Hello World'),
+),
+```
 
-    A Flutter app is itself a widget, and most widgets have a [build()][]
-    method. Instantiating and returning a widget in the app's `build()` method
-    displays the widget.
+### 4. Add the layout widget to the page
 
-    For a `Material` app, you can add the `Center` widget directly to the
-    `body` property for the home page.
+A Flutter app is itself a widget, and most widgets have a [build()][]
+method. Instantiating and returning a widget in the app's `build()` method
+displays the widget.
 
-    <!-- code/layout/hello-world/main.dart -->
-    <!-- skip -->
-    {% prettify dart %}
-    class _MyHomePageState extends State<MyHomePage> {
-      @override
-      Widget build(BuildContext context) {
-        return Scaffold(
-          appBar: AppBar(
-            title: Text(widget.title),
-          ),
-          body: Center(
-            child: Text('Hello World', style: TextStyle(fontSize: 32.0)),
-          ),
-        );
-      }
-    }
-    {% endprettify %}
-
-    {{site.alert.note}}
-      The [Material library][] implements widgets that follow [Material
-      Design][] principles. When designing your UI, you can exclusively use
-      widgets from the standard [widgets library][], or you can use widgets from
-      the Material library. You can mix widgets from both libraries, you can
-      customize existing widgets, or you can build your own set of custom
-      widgets.
-    {{site.alert.end}}
-
-    For a non-Material app, you can add the `Center` widget to the app's
-    `build()` method:
-
-    <!-- code/layout/widgets-only/main.dart -->
-    <!-- skip -->
-    {% prettify dart %}
-    // This app doesn't use any Material Components, such as Scaffold.
-    // Normally, an app that doesn't use Scaffold has a black background
-    // and the default text color is black. This app changes its background
-    // to white and its text color to dark grey to mimic a Material app.
-    import 'package:flutter/material.dart';
-
-    void main() {
-      runApp(MyApp());
-    }
-
-    class MyApp extends StatelessWidget {
-      @override
-      Widget build(BuildContext context) {
-        return Container(
-          decoration: BoxDecoration(color: Colors.white),
-          child: Center(
-            child: Text('Hello World',
-                textDirection: TextDirection.ltr,
-                style: TextStyle(fontSize: 40.0, color: Colors.black87)),
-          ),
-        );
-      }
-    }
-    {% endprettify %}
+#### Material apps
 
-    Note that, by default, the non-Material app doesn't include an `AppBar`,
-    title, or background color. If you want these features in a non-Material
-    app, you have to build them yourself. This app changes the background color
-    to white and the text to dark grey to mimic a Material app.
+For a `Material` app, you can add the `Center` widget directly to the
+`body` property for the home page.
+
+<?code-excerpt path-base="layout/non_material"?>
+<?code-excerpt "lib/main.dart (MyApp)" title?>
+```dart
+class MyApp extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return Container(
+      decoration: BoxDecoration(color: Colors.white),
+      child: Center(
+        child: Text(
+          'Hello World',
+          textDirection: TextDirection.ltr,
+          style: TextStyle(fontSize: 32.0, color: Colors.black87),
+        ),
+      ),
+    );
+  }
+}
+```
 
-That's it! When you run the app, you should see:
+{{site.alert.note}}
+  The [Material library][] implements widgets that follow [Material
+  Design][] principles. When designing your UI, you can exclusively use
+  widgets from the standard [widgets library][], or you can use widgets from
+  the Material library. You can mix widgets from both libraries, you can
+  customize existing widgets, or you can build your own set of custom
+  widgets.
+{{site.alert.end}}
 
-{% include app-figure.md img-class="site-mobile-screenshot border w-75"
-    image="ui/layout/hello-world.png" alt="Hello World" %}
+#### Non-Material apps
 
-**Dart code** (Material app): [main.dart]({{code}}/layout/hello-world/main.dart)<br>
-**Dart code** (widgets-only app): [main.dart]({{code}}/layout/widgets-only/main.dart)
+For a non-Material app, you can add the `Center` widget to the app's
+`build()` method:
+
+<?code-excerpt "lib/main.dart (MyApp)" title?>
+```dart
+class MyApp extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return Container(
+      decoration: BoxDecoration(color: Colors.white),
+      child: Center(
+        child: Text(
+          'Hello World',
+          textDirection: TextDirection.ltr,
+          style: TextStyle(fontSize: 32.0, color: Colors.black87),
+        ),
+      ),
+    );
+  }
+}
+```
+
+By default a non-Material app doesn't include an `AppBar`, title, or background
+color. If you want these features in a non-Material app, you have to build them
+yourself. This app changes the background color to white and the text to dark
+grey to mimic a Material app.
+
+<div class="row">
+<div class="col-md-6" markdown="1">
+  That's it! When you run the app, you should see _Hello World_.
+
+  App source code:
+  - [Material app]({{examples}}/layout/base)
+  - [Non-Material app]({{examples}}/layout/non_material)
+</div>
+<div class="col-md-6">
+  {% include app-figure.md img-class="site-mobile-screenshot border w-75"
+      image="ui/layout/hello-world.png" alt="Hello World" %}
+</div>
+</div>
 
 <hr>