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

ebidel · 2017-05-23T18:46:03Z

Updates screenshots
moves main readme examples to docs/readme.md
adds a "turn on logging" example to the node snippet
Beefs up the custom audit recipe and removes dupe content from the readme
Adds info on DevTools integration
Adds recipe/doc links to main readme

paulirish · 2017-05-23T18:58:48Z

readme.md

-> Helpful for CI integration
-
-  - [gulp](docs/recipes/gulp)
-
 ## Viewing a report

 Lighthouse can produce a report as JSON, HTML, or stdout CLI output.


no more stdout CLI. :)

good catch. done

paulirish · 2017-05-23T18:59:13Z

readme.md

 ## Develop

+Also see [Contributing](./CONTRIBUTING.md) for more information.


Read on for the basics of hacking on Lighthouse. Also see...

paulirish · 2017-05-23T19:01:48Z

docs/readme.md

@@ -0,0 +1,109 @@
+Useful documentation, examples, and [recipes](./recipes/) to get you started.


kinda think this should be overview.md or basics.md.

This kinda forces the user to choose a markdown file when entering /docs but i think that's good. it also means we don't have to maintain this file as a table-of-contents of all our docs

I used readme.md for that reason :)...so people would see some of the most common examples when they hit /docs. It's not really a table of contents though. [recipes](./recipes/) will give them the list of directories/md files. /readme.md has a manual list so folks can search the main repo page and find drilled in content.

well... im okay with it being readme. but let's add one more link to architecture.md at the top or so.

paulirish · 2017-05-23T19:10:45Z

These changes look great. Nice stuff. :)

paulirish · 2017-05-23T19:52:26Z

docs/readme.md

@@ -0,0 +1,109 @@
+Useful documentation, examples, and [recipes](./recipes/) to get you started.


well... im okay with it being readme. but let's add one more link to architecture.md at the top or so.

patrickhulce

a-ok by me, the readme was a bit of a monster :)

patrickhulce · 2017-05-23T20:00:22Z

readme.md

+To use Lighthouse from within the DevTools, open the tools, select the Audits panel,
+and hit "Perform an Audit...".
+
+<img width="350px" alt="Lighthouse integration in CHrome DevTools" src="https://cloud.githubusercontent.com/assets/238208/26366636/ada298f8-3fa0-11e7-9da5-ede2c906d10c.png">


nit: s/CHrome/Chrome/ :)

brendankenny

lots of little things

brendankenny · 2017-05-23T19:16:39Z

docs/readme.md

+
+function launchChromeAndRunLighthouse(url, flags, config = null) {
+  return chromeLauncher.launch().then(chrome => {
+    flags.port = chrome.port;


port ends up a distracting detail in basic usage. maybe we shouldn't have done a random port by default.. :)

i think it's worth it. but if you wanna discuss, let's open an issue?

I don't know how much it actually hurts things or how much the gains matter, so not sure if it's worth opening an issue :)

It's just when I see examples like this it seems like one more requirement to remember without any advantages for basic usage

brendankenny · 2017-05-23T19:18:55Z

docs/readme.md

+const log = require('lighthouse/lighthouse-core/lib/log');
+
+const flags = {logLevel: 'info', output: 'json'};
+log.setLevel(flags.logLevel);


log.setLevel(flags.logLevel); shouldn't need to be done by a user since the LH module does this based on flags.logLevel

you need it to see the chrome launcher's output.

you need it to see the chrome launcher's output

that seems like a chrome-launcher bug. I think we discussed removing log from there, but it should take a logLevel until/if it gets removed

brendankenny · 2017-05-23T19:19:57Z

docs/readme.md

+
+## Testing on a site with authentication
+
+Lighthouse adds `chrome-debug` to the CLI when you install it from npm.


npm/yarn?

When installed globally via npm install -g or yarn global add, a chrome-debug binary is added, which will launch a standalone Chrome instance with a debugging port open.

brendankenny · 2017-05-23T19:21:53Z

docs/readme.md

+
+// Usage:
+launchChromeAndRunLighthouse('https://example.com', flags)
+  .then(results => console.log(results));


I personally prefer your previous comment version of this (// Use results or whatever) rather than just console.logging it

brendankenny · 2017-05-23T19:25:20Z

docs/readme.md

+
+## 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:


devtoolsLogs is Page and Network now (though to be fair, this will continue to be weird to use until we get GAR)

So what are are the updates?

The devtoolsLogs array is captured from the Network domain

to

The devtoolsLogs array is captured from the Network and Page domains (a la ChromeDriver's [enableNetwork and enablePage options]

brendankenny · 2017-05-23T20:09:38Z

readme.md

@@ -234,8 +178,6 @@ yarn build-all
 # cd lighthouse-cli && yarn dev


does chrome-launcher need a tsc note too?

brendankenny · 2017-05-23T20:12:32Z

readme.md

+
+Useful documentation, examples, and recipes to get you started.
+
+**Docs**


should this be moved higher? Not as useful for first time visitors, but useful for repeat visitors. At least, when I need to get to a particular set of instructions I usually go to a project's readme and hope that it's linked to from there. Don't know what other people do :)

brendankenny · 2017-05-23T20:13:32Z

readme.md

+
+## Related Projects
+
+* [webpack-lighthouse-plugin](https://github.com/addyosmani/webpack-lighthouse-plugin) -  run Lighthouse from a Webpack build.


irregular spacing here and below?

we should fix up the wording on these, too. "gather" vs "gathers", active vs passive, etc

brendankenny · 2017-05-23T20:15:23Z

readme.md

+* [lighthouse-mocha-example](https://github.com/justinribeiro/lighthouse-mocha-example) -  gathers performance metrics via Lighthouse and tests them in Mocha
+* [pwmetrics](https://github.com/paulirish/pwmetrics/) - gather performance metrics
+* [lighthouse-hue](https://github.com/ebidel/lighthouse-hue) - Lighthouse score setting the color of Philips Hue lights
+* [lighthouse-batch](https://www.npmjs.com/package/lighthouse-batch) - Run Lighthouse over a number of sites in sequence and generating a summary report including all of their scores.


generating -> generate? Or Runs/generates. Depends on how the others end up

brendankenny · 2017-05-23T20:16:04Z

readme.md


-Our session from Google I/O 2017: architecture, writing custom audits, Github/Travis/CI integration, and more:
+> **Tip**: see [Lighthouse Architecture](./docs/architecture.md) more information


"see Lighthouse Architecture for information on terminology and architecture"?

brendankenny · 2017-05-23T20:22:19Z

readme.md

-```
-
-## Tests
+### Tests

 Some basic unit tests forked are in `/test` and run via mocha. eslint is also checked for style violations.


this sentence has morphed into something that makes no sense (and the "basic unit tests" doesn't apply anymore...lots of unit tests plus smoke tests now)

brendankenny · 2017-05-23T21:36:25Z

docs/recipes/custom-audit/readme.md


-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) information


for information

brendankenny · 2017-05-23T21:42:11Z

readme.md


-Our session from Google I/O 2017: architecture, writing custom audits, Github/Travis/CI integration, and more:
+> **Tip**: see [Lighthouse Architecture](./docs/architecture.md) more information


also needs for

brendankenny · 2017-05-23T21:43:22Z

docs/recipes/custom-audit/readme.md

+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 default.js, passes with the same name are merged together,


filename might be obscure. Maybe "when extending the default config"?

brendankenny

Those last comments, but otherwise looks good! Big improvement

brendankenny · 2017-05-23T21:47:40Z

readme.md

+* [webpack-lighthouse-plugin](https://github.com/addyosmani/webpack-lighthouse-plugin) - run Lighthouse from a Webpack build.
+* [lighthouse-mocha-example](https://github.com/justinribeiro/lighthouse-mocha-example) - gather performance metrics via Lighthouse and tests them in Mocha
+* [pwmetrics](https://github.com/paulirish/pwmetrics/) - gather performance metrics
+* [lighthouse-hue](https://github.com/ebidel/lighthouse-hue) - uses a Lighthouse score to set the color of Philips Hue lights


s/uses/use to match the other descriptions

brendankenny · 2017-05-23T21:48:30Z

readme.md

+* [pwmetrics](https://github.com/paulirish/pwmetrics/) - gather performance metrics
+* [lighthouse-hue](https://github.com/ebidel/lighthouse-hue) - uses a Lighthouse score to set the color of Philips Hue lights
+* [lighthouse-batch](https://www.npmjs.com/package/lighthouse-batch) - run Lighthouse over a number of sites and generate a summary of their metrics/scores.
+* [lighthouse-cron](https://github.com/thearegee/lighthouse-cron) - Cron multiple batch Lighthouse audits and emit results for sending to remote server.


the start of this is hard to parse, but that's what was submitted so we can leave as is for now :)

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

b354890

paulirish reviewed May 23, 2017

View reviewed changes

feedback

dd518eb

paulirish approved these changes May 23, 2017

View reviewed changes

patrickhulce reviewed May 23, 2017

View reviewed changes

brendankenny requested changes May 23, 2017

View reviewed changes

brendankenny reviewed May 23, 2017

View reviewed changes

ebidel added 3 commits May 23, 2017 13:39

feedback

6200a64

feedback

0aae84d

add back not on extending default.js

a2eeb19

brendankenny reviewed May 23, 2017

View reviewed changes

typo

6bb4995

brendankenny reviewed May 23, 2017

View reviewed changes

brendankenny approved these changes May 23, 2017

View reviewed changes

brendankenny reviewed May 23, 2017

View reviewed changes

ebidel added 2 commits May 23, 2017 15:28

tweaks

5152ad2

remove filename

d0f1848

ebidel merged commit fb86d50 into master May 24, 2017

ebidel deleted the docs branch May 24, 2017 00:29

		## Develop

		Also see [Contributing](./CONTRIBUTING.md) for more information.

		@@ -0,0 +1,109 @@
		Useful documentation, examples, and [recipes](./recipes/) to get you started.


		## Testing on a site with authentication

		Lighthouse adds `chrome-debug` to the CLI when you install it from npm.


		## 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:

		@@ -234,8 +178,6 @@ yarn build-all
		# cd lighthouse-cli && yarn dev


		Useful documentation, examples, and recipes to get you started.

		Docs


		## Related Projects

		* [webpack-lighthouse-plugin](https://github.com/addyosmani/webpack-lighthouse-plugin) - run Lighthouse from a Webpack build.


		Our session from Google I/O 2017: architecture, writing custom audits, Github/Travis/CI integration, and more:
		> Tip: see [Lighthouse Architecture](./docs/architecture.md) more information


		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) information

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

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

Conversation

ebidel commented May 23, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ebidel May 23, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

paulirish commented May 23, 2017

Choose a reason for hiding this comment

patrickhulce left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brendankenny left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brendankenny May 23, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

paulirish May 23, 2017 • edited by brendankenny Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brendankenny left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ebidel May 23, 2017 •

edited

Loading

brendankenny May 23, 2017 •

edited

Loading

paulirish May 23, 2017 •

edited by brendankenny

Loading