Use a generator to create README.md (#1001)

Easier to keep things in sync!

Author: kevmoo

json_serializable/README.md

@@ -1,3 +1,4 @@
+<!-- This content is generated. See tool/readme/readme_template.md -->
 [![Pub Package](https://img.shields.io/pub/v/json_serializable.svg)](https://pub.dev/packages/json_serializable)
 
 Provides [Dart Build System] builders for handling JSON.
@@ -62,9 +63,8 @@ Map<String, dynamic> _$PersonToJson(Person instance) => <String, dynamic>{
 
 # Running the code generator
 
-Once you have added the annotations to your code you then need to run the 
-code generator to generate the missing `.g.dart` generated dart files.
-
+Once you have added the annotations to your code you then need to run the code
+generator to generate the missing `.g.dart` generated dart files.
 
 With a Dart package, run `pub run build_runner build` in the package directory.
 
@@ -125,21 +125,19 @@ is generated:
 [JsonKey.toJson]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonKey/toJson.html
 [JsonKey.unknownEnumValue]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonKey/unknownEnumValue.html
 
-
-> Note: every `JsonSerializable` field is configurable via `build.yaml` –
-> see the table for the corresponding key.
-> If you find you want all or most of your classes with the same configuration,
-> it may be easier to specify values once in the YAML file. Values set
-> explicitly on `@JsonSerializable` take precedence over settings in
-> `build.yaml`.
+> Note: every `JsonSerializable` field is configurable via `build.yaml` – see
+> the table for the corresponding key. If you find you want all or most of your
+> classes with the same configuration, it may be easier to specify values once
+> in the YAML file. Values set explicitly on `@JsonSerializable` take precedence
+> over settings in `build.yaml`.
 
 > Note: There is some overlap between fields on `JsonKey` and
 > `JsonSerializable`. In these cases, if a value is set explicitly via `JsonKey`
-> it will take precedence over any value set on `JsonSerializable`.  
+> it will take precedence over any value set on `JsonSerializable`.
 
 # Build configuration
 
-Besides setting arguments on the associated annotation classes, you can also
+Aside from setting arguments on the associated annotation classes, you can also
 configure code generation by setting values in `build.yaml`.
 
 ```yaml
@@ -154,7 +152,7 @@ targets:
           # The default value for each is listed.
           any_map: false
           checked: false
-          constructor: ''
+          constructor: ""
           create_factory: true
           create_to_json: true
           disallow_unrecognized_keys: false

json_serializable/build.yaml

@@ -92,14 +92,21 @@ builders:
     build_to: source
     runs_before: ["json_serializable"]
 
-  _doc_builder:
-    import: "tool/doc_builder.dart"
-    builder_factories: ["docBuilder"]
-    build_extensions: {"lib/json_serializable.dart": ["doc/doc.md"]}
+  _api_table_builder:
+    import: "tool/api_table_builder.dart"
+    builder_factories: ["apiTableBuilder"]
+    build_extensions: {"lib/json_serializable.dart": ["tool/readme/api.md"]}
     build_to: source
     auto_apply: root_package
-    runs_before: ["json_serializable"]
-    required_inputs: ["doc/json_annotation_version.txt"]
+    runs_before: ["_readme_builder"]
+
+  _readme_builder:
+    import: "tool/readme_builder.dart"
+    builder_factories: ["readmeBuilder"]
+    build_extensions: {"tool/readme/api.md": ["README.md"]}
+    build_to: source
+    auto_apply: root_package
+    required_inputs: ['.dart']
 
   json_serializable:
     import: "package:json_serializable/builder.dart"

json_serializable/test/readme_test.dart

@@ -10,12 +10,14 @@ import 'package:source_gen/source_gen.dart';
 import 'package:source_helper/source_helper.dart';
 import 'package:yaml/yaml.dart';
 
-Builder docBuilder([_]) => _DocBuilder();
+import 'shared.dart';
+
+Builder apiTableBuilder([_]) => _ApiTableBuilder();
 
 const _jsonKey = 'JsonKey';
 const _jsonSerializable = 'JsonSerializable';
 
-class _DocBuilder extends Builder {
+class _ApiTableBuilder extends Builder {
   @override
   FutureOr<void> build(BuildStep buildStep) async {
     final lockFileAssetId = AssetId(buildStep.inputId.package, 'pubspec.lock');
@@ -102,12 +104,12 @@ class _DocBuilder extends Builder {
     }
 
     await buildStep.writeAsString(
-        AssetId(buildStep.inputId.package, 'doc/doc.md'), buffer.toString());
+        AssetId(buildStep.inputId.package, readmeApiPath), buffer.toString());
   }
 
   @override
   final buildExtensions = const {
-    r'lib/json_serializable.dart': ['doc/doc.md']
+    r'lib/json_serializable.dart': [readmeApiPath]
   };
 }
 

json_serializable/tool/doc_builder.dart renamed to json_serializable/tool/api_table_builder.dart

@@ -0,0 +1,96 @@
+[![Pub Package](https://img.shields.io/pub/v/json_serializable.svg)](https://pub.dev/packages/json_serializable)
+
+Provides [Dart Build System] builders for handling JSON.
+
+The builders generate code when they find members annotated with classes defined
+in [package:json_annotation].
+
+- To generate to/from JSON code for a class, annotate it with
+  `@JsonSerializable`. You can provide arguments to `JsonSerializable` to
+  configure the generated code. You can also customize individual fields by
+  annotating them with `@JsonKey` and providing custom arguments. See the table
+  below for details on the [annotation values](#annotation-values).
+
+- To generate a Dart field with the contents of a file containing JSON, use the
+  `JsonLiteral` annotation.
+
+## Setup
+
+To configure your project for the latest released version of,
+`json_serializable` see the [example].
+
+## Example
+
+Given a library `example.dart` with an `Person` class annotated with
+`@JsonSerializable()`:
+
+<!-- REPLACE example.dart -->
+
+Building creates the corresponding part `example.g.dart`:
+
+<!-- REPLACE example.g.dart -->
+
+# Running the code generator
+
+Once you have added the annotations to your code you then need to run the code
+generator to generate the missing `.g.dart` generated dart files.
+
+With a Dart package, run `pub run build_runner build` in the package directory.
+
+With a Flutter package, run `flutter pub run build_runner build` in your package
+directory.
+
+# Annotation values
+
+The only annotation required to use this package is `@JsonSerializable`. When
+applied to a class (in a correctly configured package), `toJson` and `fromJson`
+code will be generated when you build. There are three ways to control how code
+is generated:
+
+1. Set properties on `@JsonSerializable`.
+2. Add a `@JsonKey` annotation to a field and set properties there.
+3. Add configuration to `build.yaml` – [see below](#build-configuration).
+
+<!-- REPLACE api.md -->
+
+> Note: every `JsonSerializable` field is configurable via `build.yaml` – see
+> the table for the corresponding key. If you find you want all or most of your
+> classes with the same configuration, it may be easier to specify values once
+> in the YAML file. Values set explicitly on `@JsonSerializable` take precedence
+> over settings in `build.yaml`.
+
+> Note: There is some overlap between fields on `JsonKey` and
+> `JsonSerializable`. In these cases, if a value is set explicitly via `JsonKey`
+> it will take precedence over any value set on `JsonSerializable`.
+
+# Build configuration
+
+Aside from setting arguments on the associated annotation classes, you can also
+configure code generation by setting values in `build.yaml`.
+
+```yaml
+targets:
+  $default:
+    builders:
+      json_serializable:
+        options:
+          # Options configure how source code is generated for every
+          # `@JsonSerializable`-annotated class in the package.
+          #
+          # The default value for each is listed.
+          any_map: false
+          checked: false
+          constructor: ""
+          create_factory: true
+          create_to_json: true
+          disallow_unrecognized_keys: false
+          explicit_to_json: false
+          field_rename: none
+          generic_argument_factories: false
+          ignore_unannotated: false
+          include_if_null: true
+```
+
+[example]: https://github.com/google/json_serializable.dart/tree/master/example
+[dart build system]: https://github.com/dart-lang/build
+[package:json_annotation]: https://pub.dev/packages/json_annotation

json_serializable/doc/doc.md renamed to json_serializable/tool/readme/api.md

@@ -0,0 +1,87 @@
+// Copyright (c) 2019, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:build/build.dart';
+import 'package:path/path.dart' as p;
+
+import 'shared.dart';
+
+Builder readmeBuilder([_]) => _ReadmeBuilder();
+
+class _ReadmeBuilder extends Builder {
+  @override
+  FutureOr<void> build(BuildStep buildStep) async {
+    final templateAssetId =
+        AssetId(buildStep.inputId.package, 'tool/readme/readme_template.md');
+    final templateAssetContent = await buildStep.readAsString(templateAssetId);
+
+    Future<String> getExampleContent(String fileName) async {
+      final content = await buildStep.readAsString(
+        AssetId(buildStep.inputId.package, p.join('example', fileName)),
+      );
+
+      final lines = LineSplitter.split(content);
+
+      var lastHadContent = false;
+
+      // All lines with content, except those starting with `/`.
+      // Also exclude blank lines that follow other blank lines
+      final cleanedSource = lines.where((l) {
+        if (l.startsWith(r'/')) {
+          return false;
+        }
+
+        if (l.trim().isNotEmpty) {
+          lastHadContent = true;
+          return true;
+        }
+
+        if (lastHadContent) {
+          lastHadContent = false;
+          return true;
+        }
+
+        return false;
+      }).join('\n');
+
+      return '''
+```dart
+$cleanedSource
+```''';
+    }
+
+    final replacements = {
+      'api.md': await buildStep
+          .readAsString(AssetId(buildStep.inputId.package, readmeApiPath)),
+      'example.dart': await getExampleContent('example.dart'),
+      'example.g.dart': await getExampleContent('example.g.dart'),
+    };
+
+    final expandedContent =
+        templateAssetContent.replaceAllMapped(_replaceRegexp, (match) {
+      final replacementKey = match.group(1)!;
+      return replacements[replacementKey]!.trim();
+    }).trim();
+
+    await buildStep.writeAsString(
+      AssetId(buildStep.inputId.package, _readmePath),
+      '''
+<!-- This content is generated. See $_templatePath -->
+$expandedContent
+''',
+    );
+  }
+
+  @override
+  final buildExtensions = const {
+    readmeApiPath: [_readmePath]
+  };
+}
+
+const _templatePath = 'tool/readme/readme_template.md';
+const _readmePath = 'README.md';
+
+final _replaceRegexp = RegExp(r'<!-- REPLACE ([\w\d\.]+) -->');

json_serializable/tool/readme/readme_template.md

@@ -7,6 +7,8 @@ import 'dart:io';
 import 'package:build/build.dart';
 import 'package:yaml/yaml.dart';
 
+const readmeApiPath = 'tool/readme/api.md';
+
 // Until we have verification in pkg:build and friends
 // https://github.com/dart-lang/build/issues/590
 Builder validate(String builderName, Builder builder) {