Docs: update readme, add docs/readme, modernize a bit

docs/readme.md

@@ -0,0 +1,109 @@
+Useful documentation, examples, and [recipes](./recipes/) to get you started.
+
+## Using programmatically
+
+The example below shows how to run Lighthouse programmatically as a Node module. It
+assumes you've installed Lighthouse as a dependency (`yarn add --dev lighthouse`).
+
+```javascript
+const lighthouse = require('lighthouse');
+const chromeLauncher = require('lighthouse/chrome-launcher/chrome-launcher');
+
+function launchChromeAndRunLighthouse(url, flags, config = null) {
+  return chromeLauncher.launch().then(chrome => {
+    flags.port = chrome.port;
+    return lighthouse(url, flags, config).then(results =>
+      chrome.kill().then(() => results)
+    );
+  });
+}
+
+const flags = {output: 'json'};
+
+// Usage:
+launchChromeAndRunLighthouse('https://example.com', flags)
+  .then(results => console.log(results));
+```
+
+### Turn on logging
+
+If you want to see log output as Lighthouse runs, include the `log` module
+and set an appropriate logging level in your code. You'll also need to pass
+the `logLevel` flag when calling `lighthouse`.
+
+```javascript
+const log = require('lighthouse/lighthouse-core/lib/log');
+
+const flags = {logLevel: 'info', output: 'json'};
+log.setLevel(flags.logLevel);
+
+launchChromeAndRunLighthouse('https://example.com', flags).then(...);
+```
+
+## Testing on a site with authentication
+
+Lighthouse adds `chrome-debug` to the CLI when you install it from npm.
+
+- Run `chrome-debug`
+- open and login to your site
+- in a separate terminal tab `lighthouse http://mysite.com`
+
+## Testing on a mobile device
+
+Lighthouse can run against a real mobile device. You can follow the [Remote Debugging on Android (Legacy Workflow)](https://developer.chrome.com/devtools/docs/remote-debugging-legacy) up through step 3.3, but the TL;DR is install & run adb, enable USB debugging, then port forward 9222 from the device to the machine with Lighthouse.
+
+You'll likely want to use the CLI flags `--disable-device-emulation --disable-cpu-throttling` and potentially `--disable-network-throttling`.
+
+```sh
+$ adb kill-server
+
+$ adb devices -l
+* daemon not running. starting it now on port 5037 *
+* daemon started successfully *
+00a2fd8b1e631fcb       device usb:335682009X product:bullhead model:Nexus_5X device:bullhead
+
+$ adb forward tcp:9222 localabstract:chrome_devtools_remote
+
+$ lighthouse --disable-device-emulation --disable-cpu-throttling https://mysite.com
+```
+
+## Lighthouse as trace processor
+
+Lighthouse can be used to analyze trace and performance data collected from other tools (like WebPageTest and ChromeDriver). The `traces` and `devtoolsLogs` artifact items can be provided using a string for the absolute path on disk. The `devtoolsLogs` array is captured from the Network domain (a la ChromeDriver's [`enableNetwork` option](https://sites.google.com/a/chromium.org/chromedriver/capabilities#TOC-perfLoggingPrefs-object)) and reformatted slightly. As an example, here's a trace-only run that's reporting on user timings and critical request chains:
+
+### `config.json`
+
+```json
+{
+  "audits": [
+    "user-timings",
+    "critical-request-chains"
+  ],
+
+  "artifacts": {
+    "traces": {
+      "defaultPass": "/User/me/lighthouse/lighthouse-core/test/fixtures/traces/trace-user-timings.json"
+    },
+    "devtoolsLogs": {
+      "defaultPass": "/User/me/lighthouse/lighthouse-core/test/fixtures/traces/perflog.json"
+    }
+  },
+
+  "aggregations": [{
+    "name": "Performance Metrics",
+    "description": "These encapsulate your app's performance.",
+    "scored": false,
+    "categorizable": false,
+    "items": [{
+      "audits": {
+        "user-timings": { "expectedValue": 0, "weight": 1 },
+        "critical-request-chains": { "expectedValue": 0, "weight": 1}
+      }
+    }]
+  }]
+}
+```
+
+Then, run with: `lighthouse --config-path=config.json http://www.random.url`
+
+The traceviewer-based trace processor from [node-big-rig](https://github.com/GoogleChrome/node-big-rig/tree/master/lib) was forked into Lighthouse. Additionally, the [DevTools' Timeline Model](https://github.com/paulirish/devtools-timeline-model) is available as well. There may be advantages for using one model over another.

docs/recipes/custom-audit/readme.md

@@ -1,11 +1,34 @@
-# Basic custom audit recipe for Lighthouse
+# Basic Custom Audit Recipe
 
-A hypothetical site measures the time from navigation start to when the page has initialized and the main search box is ready to be used. It saves that value in a global variable, `window.myLoadMetrics.searchableTime`.
+> **Tip**: see [Lighthouse Architecture](../../../docs/architecture.md) more information
+on terminology and architecture.
 
-This Lighthouse [gatherer](searchable-gatherer.js)/[audit](searchable-audit.js) pair will take that value from the context of the page and test whether or not it stays below a test threshold.
+## What this example does
 
-The config file tells Lighthouse where to find the gatherer and audit files, when to run them, and how to incorporate their output into the Lighthouse report.
+This example shows how to write a custom Lighthouse audit for a hypothetical site
+which measures the time from navigation start to when the page has initialized.
+The page is considered fully initialized when the main search box ("hero element")
+is ready to be used. The page saves that time in a global variable called `window.myLoadMetrics.searchableTime`.
 
-## Run
-With site running:
-`lighthouse --config-path=custom-config.js https://test-site.url`
+## The Audit, Gatherer, and Config
+
+[searchable-gatherer.js](searchable-gatherer.js) - a [Gatherer](https://github.com/GoogleChrome/lighthouse/blob/master/docs/architecture.md#components--terminology) that collects `window.myLoadMetrics.searchableTime`
+from the context of the page.
+
+[searchable-audit.js](searchable-audit.js) - an [Audit](https://github.com/GoogleChrome/lighthouse/blob/master/docs/architecture.md#components--terminology) that tests whether or not `window.myLoadMetrics.searchableTime`
+stays below a 4000ms. In other words, Lighthouse will consider the audit "passing"
+in the report if the search box initializes within 4s.
+
+[custom-config.js](custom-config.js) - this file tells Lighthouse where to
+find the gatherer and audit files, when to run them, and how to incorporate their
+output into the Lighthouse report. In this example, we have extended [Lighthouse's
+default configuration](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/default.js). If you're extending Lighthouse's default, passes with the same name are merged together, all other arrays will be concatenated, and primitive values will override the defaults.
+
+## Run the configuration
+
+Lastly, tell Lighthouse to run your audit(s) by passing the `--config-path` flag
+with your configuration:
+
+```sh
+lighthouse --config-path=custom-config.js https://example.com
+```