dart-archive / dart-doc-syncer

A utility for syncing Dart examples for the public docs

dart-doc-syncer

A utility for syncing Dart examples for the AngularDart docs (https://webdev.dartlang.org/angular).

Example sources are read from the dart-lang/site-webdev repo and written to individual repos under angular-examples.

For specific commands to use when updating the AngularDart docs and examples, see https://github.com/dart-lang/site-webdev/wiki/Updating-Angular-docs.

Syncing a single example

Use the example name as an argument. For example:

dart dart_doc_syncer architecture

Syncing multiple examples

The --match option takes a regular expression as an argument. The dart_doc_syncer will sync all examples that match the regex. To sync all examples, you can use . (dot) as a "match-all" pattern:

dart dart_doc_syncer --match .

Options

dart ~/GITHUB/dart-doc-syncer/bin/dart_doc_syncer.dart --help

Syncs Angular docs example apps.

Usage: dart_doc_syncer [options] [<exampleName> | <examplePath> <exampleRepo>]

-h, --help                Show this usage information
-b, --branch              <branch-name>
                          Git branch to fetch webdev and examples from
                          (defaults to "master")

-n, --dry-run             Show which commands would be executed but make (almost) no changes;
                          only the temporary directory will be created

-f, --force-build         Forces build of example app when sources have not changed
-g, --gh-pages-app-dir    <path>
                          Directory in which the generated example apps will be placed (gh-pages branch)

-k, --keep-tmp            Do not delete temporary working directory once done
    --pub-get             Use `pub get` instead of `pub upgrade` before building apps
-p, --[no-]push           Prepare updates and push to example repo
                          (defaults to on)

-m, --match               <dart-regexp>
                          Sync all examples having a data file (.docsync.json)
                          and whose repo path matches the given regular expression;
                          use "." to match all

    --skip                <dart-regexp>
                          Negative filter applied to the project list created by use of the --match option

    --url                 [dev|main]
                          Webdev site URL to use in generated README.
                          (defaults to "main")

-u, --user                <user-id>
                          GitHub id of repo to fetch examples from
                          (defaults to "dart-lang")

-v, --verbose             
    --web-compiler        <compiler>, either dart2js or dartdevc
                          (defaults to "dart2js")

-w, --work-dir            <path>
                          Path to a working directory; when unspecified a system-generated path to a temporary directory is used

dart-doc-syncer's Issues

Sync should fetch examples from new home repo dart-lang/site-webdev

Examples are now under https://github.com/dart-lang/site-webdev.

Add a home page

Add guide/lifecycle-hooks example

Fix README.md formatting

E.g., see https://github.com/angular-examples/quickstart/blob/master/README.md looks like this:

You can run a hosted copy of this sample. Or run your own copy:

Clone or [download][] this repo. [download]: //github.com/angularexamples/quickstart/archive/master.zip
Get the dependencies:
pub get 3. Launch a development server:
pub serve 4. Open a browser to http://localhost:8080.

cc @kwalrath

Reduce/clarify command output

I'd like to see much less output from dart bin/sync_all.dart — just an indication of which directories it looked at, which repos it updated, and whether it succeeded or failed. Something like this:

Source repo: https://github.com/angular/angular.io
Processing public/docs/_examples/template-syntax
  Sample changed!
  Updating repo: https://github.com/angular-examples/template-syntax
Processing public/docs/_examples/pipes
  No changes.
Processing public/docs/_examples/server-communication
  No changes.
...
Processed 10 samples.
Updated 1 repo.

Details:
When I ran dart bin/sync_all.dart today, I got 117 lines of output. Most of it is prefixed with FINE, a bit of it is prefixed with SEVERE. I initially took "FINE" as meaning "OK" and "SEVERE" as meaning "OMG: ERROR!".

Also, every example has a line like this:

FINE: 2016-04-21 09:02:31.946215: Pushing generated example to [email protected]:angular-examples/template-syntax.git.

But it's not really pushing unless it also has a message like this:

FINE: 2016-04-21 09:02:31.976059: Pushing changes for /Users/kathyw/GITHUB/dart-doc-syncer/bin/.tmp/template-syntax.

I had to look at the actual repos to see whether they were updated.

Also the current output has a misspelling: "Comitting". :)

Add a link from the repo to the running example

The README.md files (e.g. structural-directives's README) currently say something like this:

Welcome to the example application used in angular.io/dart's
structural-directives page.

To run your own copy:

I'd like to add a prominent link to where they can find the already built version. Something like this:

Welcome to the example application used in angular.io/dart's
structural-directives page.
To run this app, go to http://angular-examples.github.io/structural-directives.

To get the source code and run your own copy:

For Angular 5, build using dart2js

Under the new build system, dartdevc is the default web compiler. Until dartdevc is recommended for use in production, continue to using dart2js -- in particular, because dartdevc deploy don't currently work :), see dart-lang/build#896.

This is the DDS request for https://github.com/dart-lang/site-webdev/issues/1284.

Adjust to new example folder layout

See

• https://github.com/dart-lang/site-webdev/issues/464
• https://github.com/dart-lang/site-webdev/issues/468

cc @kwalrath

Add shared styles.css to generated code.

Can be found here https://github.com/angular/angular.io/blob/master/public/docs/_examples/styles.css and is used by all the examples.

Make test deployments easy

@chalin has sometimes run dart-doc-syncer before tests have passed, because dds is faster than the tests, and being able to visit the running apps makes spot checking is easy.

It'd be nice if it were easy to automate a local-only version of dds. So... thinking of what'd be necessary... you'd copy all the files locally and start a server, plus you'd have a list of all the examples so it'd be easy to spot check them.

Perhaps this could be added to --dry-run?

Which reminds me... we should document the command-line options in the README. I can do that.

Include more information in generated commit message.

Sync with 3b768a3

Synced with angular/angular.io master branch, commit 3b768a3:
public/docs/_examples/template-syntax/dart.

Change generated READMEs to conform to CommonMark markdown

See @kwalrath's googlearchive/quickstart#1 illustrates a fix to a README so that it conforms to CommonMark.

• https://githubengineering.com/a-formal-spec-for-github-markdown/
• github/markup#1018

Craft a better, more appealing README for generated examples.

Link to other interesting examples or where a complete list can be found.
Links to other good reads about the subject?
Point to installation instructions for Angular, Dart?

Add guide/structural-directives example

Add guide/component-styles example

Once angular/angular.io#1320 is merged.

Switch to using new template parser for Angular 5 apps

Cf. https://github.com/dart-lang/site-webdev/issues/1281

site-webdev -> site-angulardart

See comments on googlearchive/toh-6#8.

Add args dependency to pubspec.yaml

dart_doc_syncer depends only on logging and path, but it also imports libs from the args package. (It gets by because of transitive dependencies.)

Add toh-1 to toh-5 examples