Docs: update readme, add docs/readme, modernize a bit (#2341)

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

* feedback

* feedback

* feedback

* add back not on extending default.js

* typo

* tweaks

* remove filename

docs/readme.md

@@ -0,0 +1,114 @@
+This directory contains useful documentation, examples (keep reading),
+and [recipes](./recipes/) to get you started. For an overview of Lighthouse's
+internals, see [Lighthouse Architecture](architecture.md).
+
+## 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 => {
+  // Use 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
+
+When installed globally via `npm i -g lighthouse` or `yarn global add lighthouse`,
+`chrome-debug` is added to your `PATH`. This binary launches a standalone Chrome
+instance with an open debugging port.
+
+- Run `chrome-debug`
+- navigate to and log in 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` and `Page` domains (a la ChromeDriver's [enableNetwork and enablePage options]((https://sites.google.com/a/chromium.org/chromedriver/capabilities#TOC-perfLoggingPrefs-object)).
+
+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`

docs/recipes/custom-audit/readme.md

@@ -1,11 +1,32 @@
-# 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) for 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 search page. The page is considered fully initialized when the main search box (the page's "hero element") is ready to be used. When this happens, the page uses `performance.now()` to find the time since navigation start and saves the value 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 threshold. 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. This example extends [Lighthouse's
+default configuration](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/default.js).
+
+**Note**: when extending the default configuration file, passes with the same name are merged together, all other arrays will be concatenated, and primitive values will override the defaults.
+
+## Run the configuration
+
+Run Lighthouse with the custom audit by using the `--config-path` flag with your configuration file:
+
+```sh
+lighthouse --config-path=custom-config.js https://example.com
+```