Permalink
Browse files

Should generate documentation in Kindle mobi format

  • Loading branch information...
1 parent a1db319 commit fbd8addc404f8e296c5e4998deca9389159f9a21 @assaf committed Dec 5, 2012
Showing with 139 additions and 184 deletions.
  1. +0 −39 doc/new-browser.md
  2. +111 −139 doc/new/README.md
  3. +24 −6 doc/new/generate.coffee
  4. +4 −0 doc/new/style/zombie.css
View
39 doc/new-browser.md
@@ -1,39 +0,0 @@
-
-
-`browser.assert`
-
-Methods for making assertions against the browser, such as
-`browser.assert.element(".foo")`.
-
-See *Assertions* section for detailed discussion.
-
-
-`browser.console`
-
-Provides access to the browser console (same as `window.console`).
-
-
-`browser.referer`
-
-You can use this to set the HTTP Referer header.
-
-
-`browser.resources`
-
-Access to history of retrieved resources. Also provides methods for retrieving
-resources and managing the resource pipeline. When things are not going your
-way, try calling `browser.resources.dump()`.
-
-See *Resources* section for detailed discussion.
-
-
-`browser.tabs`
-
-Array of all open tabs (windows). Allows you to operate on more than one open
-window at a time.
-
-See *Tabs* section for detailed discussion.
-
-
-`browser.eventLoop`
-`browser.errors`
View
250 doc/new/README.md
@@ -2,51 +2,49 @@
## Browser
-### `browser.assert`
+#### `browser.assert`
Methods for making assertions against the browser, such as
`browser.assert.element(".foo")`.
See [Assertions](#assertions) for detailed discussion.
-### `browser.console`
+#### `browser.console`
Provides access to the browser console (same as `window.console`).
-### `browser.referer`
+#### `browser.referer`
You can use this to set the HTTP Referer header.
-### `browser.resources`
+#### `browser.resources`
Access to history of retrieved resources. Also provides methods for retrieving
resources and managing the resource pipeline. When things are not going your
way, try calling `browser.resources.dump()`.
See [Resources](#resources) for detailed discussion.
-### `browser.tabs`
+#### `browser.tabs`
Array of all open tabs (windows). Allows you to operate on more than one open
window at a time.
See [Tabs](#tabs) for detailed discussion.
-### `browser.eventLoop`
-### `browser.errors`
+#### `browser.eventLoop`
+#### `browser.errors`
### Extending The Browser
-```
-Browser.extend(function(browser) {
- browser.on("console", function(level, message) {
- logger.log(message);
- });
- browser.on("log", function(level, message) {
- logger.log(message);
- });
-});
-```
+ Browser.extend(function(browser) {
+ browser.on("console", function(level, message) {
+ logger.log(message);
+ });
+ browser.on("log", function(level, message) {
+ logger.log(message);
+ });
+ });
@@ -81,59 +79,59 @@ first tab would be the window with the document "/foo".
The following operations are used for managing tabs:
-### `browser.close(window)`
+#### `browser.close(window)`
Closes the tab with the given window.
-### `browser.close()`
+#### `browser.close()`
Closes the currently open tab.
-### `browser.tabs`
+#### `browser.tabs`
Returns an array of all open tabs.
-### `browser.tabs[number]`
+#### `browser.tabs[number]`
Returns the tab with that index number.
-### `browser.tabs[string]`
-### `browser.tabs.find(string)`
+#### `browser.tabs[string]`
+#### `browser.tabs.find(string)`
Returns the tab with that name.
-### `browser.tabs.closeAll()`
+#### `browser.tabs.closeAll()`
Closes all tabs.
-### `browser.tabs.current`
+#### `browser.tabs.current`
Returns the currently active tab.
-### `browser.tabs.current = window`
+#### `browser.tabs.current = window`
Changes the currently active tab. You can set it to a window (e.g. as currently
returned from `browser.current`), a window name or the tab index number.
-### `browser.tabs.dump(output)`
+#### `browser.tabs.dump(output)`
Dump a list of all open tabs to standard output, or the output stream.
-### `browser.tabs.index`
+#### `browser.tabs.index`
Returns the index of the currently active tab.
-### `browser.tabs.length`
+#### `browser.tabs.length`
Returns the number of currently opened tabs.
-### `browser.open(url: "http://example.com")`
+#### `browser.open(url: "http://example.com")`
Opens and returns a new tab. Supported options are:
- `name` - Window name.
- `url` - Load document from this URL.
-### `browser.window`
+#### `browser.window`
Returns the currently active window, same as `browser.tabs.current.`
@@ -151,11 +149,9 @@ can execute directly against the browser object. For example, to check that a
page load completed successfully, you may do:
-```
-browser.assert.success();
-browser.assert.text("title", "My Awesome Site");
-browser.assert.element("#main");
-```
+ browser.assert.success();
+ browser.assert.text("title", "My Awesome Site");
+ browser.assert.element("#main");
Assertions that take an expected value, will compare that against the actual
value. The expected value can be a primitive JavaScript value (string, number,
@@ -173,24 +169,24 @@ you want to let the assertion format the message for you.
The following assertions are available:
-### `browser.assert.attribute(selector, name, expected, message)`
+#### `browser.assert.attribute(selector, name, expected, message)`
Assert the named attribute of the selected element(s) has the expected value.
Fails if no elements found.
-### `browser.assert.className(selector, className, message)`
+#### `browser.assert.className(selector, className, message)`
Asserts that selected element(s) has the that and only that class name.
-### `browser.assert.cookie(name, expected, message)`
+#### `browser.assert.cookie(name, expected, message)`
Asserts that a cookie with the given name has the expected value.
-### `browser.assert.element(selector, message)`
+#### `browser.assert.element(selector, message)`
Assert that an element matching selector exists.
-### `browser.assert.elements(selector, count, message)`
+#### `browser.assert.elements(selector, count, message)`
Assert how many elements exist that match the selector.
@@ -200,60 +196,60 @@ The count can be a number, or an object with the following properties:
- `atMost` - Expect to find at most that many elements.
- `exactly` - Expect to find exactly that many elements.
-### `browser.assert.evaluate(expression, expected, message)`
+#### `browser.assert.evaluate(expression, expected, message)`
Evaluates the JavaScript expression in the browser context. With one argument,
asserts that the value is true. With two or three arguments, asserts that the
value of the expression matches the expected value.
-### `browser.assert.global(name, expected, message)`
+#### `browser.assert.global(name, expected, message)`
Asserts that the global (window) property has the expected value.
-### `browser.assert.hasClass(selector, className, message)`
+#### `browser.assert.hasClass(selector, className, message)`
Asserts that selected element(s) has the expected class name (it may have many
other class names).
-### `browser.assert.hasFocus(selector, message)`
+#### `browser.assert.hasFocus(selector, message)`
Asserts that selected element has the focus.
-### `browser.assert.input(selector, expected, message)`
+#### `browser.assert.input(selector, expected, message)`
Asserts that selected input field (text field, text area, etc) has the expected
value.
-### `browser.assert.hasNoClass(selector, className, message)`
+#### `browser.assert.hasNoClass(selector, className, message)`
Asserts that selected element(s) does not have the expected class name (it may
have many other class names).
-### `browser.assert.prompted(messageShown, message)`
+#### `browser.assert.prompted(messageShown, message)`
Assert that browser prompted with a given message.
-### `browser.assert.redirected(message)`
+#### `browser.assert.redirected(message)`
Asserts that browser was redirected when retrieving the current page.
-### `browser.assert.success(message)`
+#### `browser.assert.success(message)`
Assert that the last page load returned status code 200.
-### `browser.assert.status(code, message)`
+#### `browser.assert.status(code, message)`
Assert that the last page load returned the expected status code.
-### `browser.assert.style(selector, style, expected, message)`
+#### `browser.assert.style(selector, style, expected, message)`
Assert that the style property of the selected element(s) the expected value.
-### `browser.assert.text(selector, expected, message)`
+#### `browser.assert.text(selector, expected, message)`
Assert that text content of selected element(s) matche the expected value.
-### `browser.assert.url(url, message)`
+#### `browser.assert.url(url, message)`
Asserts that current page has the expected URL.
@@ -263,118 +259,114 @@ properties are matched against the URL.
For example:
-```
-browser.assert.url({ pathame: "/resource" });
-browser.assert.url({ query: { name: "joedoe" } });
-```
+ browser.assert.url({ pathame: "/resource" });
+ browser.assert.url({ query: { name: "joedoe" } });
### Add Your Own Assertions
You can add more assertions by adding methods to the prototype of
`Browser.Assert`. These have access to the browser as a property, for example:
-```
-// Asserts the browser has the expected number of open tabs.
-Browser.Assert.prototype.openTabs = function(expected, message) {
- assert.equal(this.browser.tabs.length, expected, message);
-};
-```
+ // Asserts the browser has the expected number of open tabs.
+ Browser.Assert.prototype.openTabs = function(expected, message) {
+ assert.equal(this.browser.tabs.length, expected, message);
+ };
## Events
-### `console (level, messsage)`
+#### `console (level, messsage)`
Emitted whenever a message is printed to the console (`console.log`,
`console.error`, `console.trace`, etc).
The first argument is the logging level, one of `debug`, `error`, `info`, `log`,
`trace` or `warn`. The second argument is the message to log.
-### `active (window)`
+#### `active (window)`
Emitted when this window becomes the active window.
-### `closed (window)`
+#### `closed (window)`
Emitted when a window is closed.
-### `done ()`
+#### `done ()`
Emitted whenever the event loop is empty.
-### `evaluated (code, result, filename)`
+#### `evaluated (code, result, filename)`
Emitted whenever JavaScript code is evaluated. The first argument is the
JavaScript function or source code, the second argument the result, and the
third argument is the filename.
-### `event (event, target)`
+#### `event (event, target)`
Emitted whenever a DOM event is fired on the target element, document or window.
-### `focus (element)`
+#### `focus (element)`
Emitted whenever an input element receives the focus.
-### `inactive (window)`
+#### `inactive (window)`
Emitted when this window is no longer the active window.
-### `interval (function, interval)`
+#### `interval (function, interval)`
Emitted whenever an interval event (`setInterval`) is fired, with the function and
interval.
-### `link (url, target)`
+#### `link (url, target)`
Emitted when a link is clicked and the browser navigates to a new URL. Includes
the URL and the target window (default to `_self`).
-### `loaded (document)`
+#### `loaded (document)`
Emitted when a document is loaded into a window or frame. This event is emitted
after the HTML is parsed and loaded into the Document object.
-### `loading (document)`
+#### `loading (document)`
Emitted when a document is loaded into a window or frame. This event is emitted
with an empty Document object, before parsing the HTML response.
-### `opened (window)`
+#### `opened (window)`
Emitted when a window is opened.
-### `redirect (request, response)`
+#### `redirect (request, response)`
Emitted when following a redirect.
The first argument is the request, the second argument is the redirect response.
The URL of the new resource to retrieve is given by `response.url`.
-### `request (request, target)`
+#### `request (request, target)`
Emitted before making a request to retrieve the resource.
The first argument is the request object (see *Resources* for more details), the
second argument is the target element/document.
-### `response (request, response, target)`
+#### `response (request, response, target)`
Emitted after receiving the response when retrieving a resource.
The first argument is the request object (see *Resources* for more details), the
second argument is the response that is passed back, and the third argument is
the target element/document.
-### `submit (url, target)`
+#### `submit (url, target)`
Emitted when a form is submitted. Includes the action URL and the target window
(default to `_self`).
-### `timeout (function, delay)`
+#### `timeout (function, delay)`
Emitted whenever a timeout event (`setTimeout`) is fired, with the function and
delay.
@@ -457,20 +449,16 @@ server response.
For example, to mock a response:
-```
-browser.resources.mock("http://3rd.party.api/v1/request", {
- statusCode: 200,
- headers: { "ContentType": "application/json" },
- body: JSON.stringify({ "count": 5 })
-})
-```
+ browser.resources.mock("http://3rd.party.api/v1/request", {
+ statusCode: 200,
+ headers: { "ContentType": "application/json" },
+ body: JSON.stringify({ "count": 5 })
+ })
In the real world, servers and networks often fail. You can test to for these
conditions by asking Zombie to simulate a failure. For example:
-```
-browser.resource.fail("http://3rd.party.api/v1/request");
-```
+ browser.resource.fail("http://3rd.party.api/v1/request");
Use `mock` to simulate a server failing to process a request by returning status
code 500. Use `fail` to simulate a server that is not accessible.
@@ -484,16 +472,12 @@ Occassionally you'll need to force the server to return resources in a different
order, for example, to check what happens when script A loads after script B.
You can introduce a delay into any response as simple as:
-```
-browser.resources.delay("http://3d.party.api/v1/request", 50);
-```
+ browser.resources.delay("http://3d.party.api/v1/request", 50);
Once you're done mocking, failing or delaying a resource, restore it to its
previous state:
-```
-browser.resources.restore("http://3d.party.api/v1/request");
-```
+ browser.resources.restore("http://3d.party.api/v1/request");
### Operating On Resources
@@ -507,32 +491,24 @@ The `browser.resources` object exposes `get`, `post` and the more generic
For example, to download a document:
-```
-browser.resources.get("http://some.service", function(error, response) {
- console.log(response.statusText);
- console.log(response.body);
-});
-```
-
-```
-var params = { "count": 5 };
-browser.resources.post("http://some.service", { params: params }, function(error, response) {
- . . .
-});
-```
-
-```
-var headers = { "Content-Type": "application/x-www-form-urlencoded" };
-browser.resources.post("http://some.service", { headers: headers, body: "count=5" }, function(error, response) {
- . . .
-});
-```
-
-```
-browser.resources.request("DELETE", "http://some.service", function(error) {
- . . .
-});
-```
+ browser.resources.get("http://some.service", function(error, response) {
+ console.log(response.statusText);
+ console.log(response.body);
+ });
+
+ var params = { "count": 5 };
+ browser.resources.post("http://some.service", { params: params }, function(error, response) {
+ . . .
+ });
+
+ var headers = { "Content-Type": "application/x-www-form-urlencoded" };
+ browser.resources.post("http://some.service", { headers: headers, body: "count=5" }, function(error, response) {
+ . . .
+ });
+
+ browser.resources.request("DELETE", "http://some.service", function(error) {
+ . . .
+ });
### The Resource Chain
@@ -554,28 +530,24 @@ processing.
To add a new filter at the end of the pipeline:
-```
-browser.resources.addFilter(function(request, next) {
- // Let's delay this request by 1/10th second
- setTimeout(function() {
- Resources.httpRequest(request, next);
- }, Math.random() * 100);
-});
-```
+ browser.resources.addFilter(function(request, next) {
+ // Let's delay this request by 1/10th second
+ setTimeout(function() {
+ Resources.httpRequest(request, next);
+ }, Math.random() * 100);
+ });
If you need anything more complicated, you can access the pipeline directly via
`browser.resources.filters`.
You can add filters to all browsers via `Browser.Resources.addFilter`. These
filters are automatically added to every new `browser.resources` instance.
-```
-Browser.Resources.addFilter(function(request, response, next) {
- // Log the response body
- console.log("Response body: " + response.body);
- next();
-});
-```
+ Browser.Resources.addFilter(function(request, response, next) {
+ // Log the response body
+ console.log("Response body: " + response.body);
+ next();
+ });
That list of filters is available from `Browser.Resources.filters`.
View
30 doc/new/generate.coffee
@@ -2,14 +2,22 @@
{ execFile } = require("child_process")
File = require("fs")
-console.log "Processing README.md ..."
+
+console.log "Generating index.html ..."
layout = File.readFileSync("style/layout.html").toString()
execFile "markdown", ["README.md"], (error, stdout, stderr)->
if error
- throw error
+ console.error("Note: if you haven't already, brew install markdown")
+ console.error(error.message)
+ process.exit(1)
+
+ # Add IDs for all headers so they can be references
+ addIDToHeader = (match, level, textContent)->
+ id = textContent.replace(/\s+/, "_").toLowerCase()
+ return "<h#{level} id=\"#{id}\">#{textContent}</h#{level}>"
+ content = stdout.replace(/<h([1-3])>(.*)<\/h[1-3]>/g, addIDToHeader)
- console.log "Generating index.html ..."
- html = layout.replace("{content}", stdout)
+ html = layout.replace("{content}", content)
File.writeFileSync("index.html", html)
console.log "Generating zombie.pdf ..."
@@ -23,9 +31,19 @@ execFile "markdown", ["README.md"], (error, stdout, stderr)->
"index.html",
"zombie.pdf"
]
-
execFile "wkhtmltopdf", pdfOptions, (error, stdout, stderr)->
if error
- throw error
+ console.error("Note: if you haven't already, brew install wkhtmltopdf")
+ console.error(error.message)
console.log "Generating zombie.mobi ..."
+ kindleOptions = [
+ "-c2"
+ "index.html",
+ "-o", "zombie.mobi"
+ ]
+ execFile "kindlegen", kindleOptions, (error, stdout, stderr)->
+ console.log(stdout)
+
+ console.log "Done"
+ process.exit(0)
View
4 doc/new/style/zombie.css
@@ -32,6 +32,10 @@ pre, code {
overflow-y: hidden;
white-space: pre;
}
+pre {
+ background: #eef;
+ padding: 0.6em;
+}
a {
color: steelblue;
text-decoration: none;

0 comments on commit fbd8add

Please sign in to comment.