docs(all): improve api documentation (#166)

This commit closes #147.

@pageobject/flexible-protractor/README.md

@@ -1,6 +1,6 @@
 # @pageobject/flexible-protractor [![Package Version][badge-npm-image]][badge-npm-link] [![Build Status][badge-travis-image]][badge-travis-link] [![Coverage Status][badge-coveralls-image]][badge-coveralls-link]
 
-> Run your [@pageobject/flexible][internal-readme-flexible]-based tests using [Protractor][external-protractor].
+> Run your [@pageobject/flexible][internal-api-flexible]-based tests using [Protractor][external-protractor].
 
 ## Installation
 
@@ -22,7 +22,7 @@ Built by (c) Clemens Akens. Released under the terms of the [MIT License][intern
 [badge-npm-link]: https://yarnpkg.com/en/package/@pageobject/flexible-protractor
 [badge-travis-image]: https://travis-ci.org/clebert/pageobject.svg?branch=master
 [badge-travis-link]: https://travis-ci.org/clebert/pageobject
+[internal-api-flexible]: https://pageobject.js.org/api/flexible/
 [internal-api-flexible-protractor]: https://pageobject.js.org/api/flexible-protractor/
 [internal-license]: https://github.com/clebert/pageobject/blob/master/LICENSE
-[internal-readme-flexible]: https://github.com/clebert/pageobject/tree/master/@pageobject/flexible/README.md
 [external-protractor]: https://www.protractortest.org/#/

@pageobject/flexible-puppeteer/README.md

@@ -1,6 +1,6 @@
 # @pageobject/flexible-puppeteer [![Package Version][badge-npm-image]][badge-npm-link] [![Build Status][badge-travis-image]][badge-travis-link] [![Coverage Status][badge-coveralls-image]][badge-coveralls-link]
 
-> Run your [@pageobject/flexible][internal-readme-flexible]-based tests using [Puppeteer][external-puppeteer].
+> Run your [@pageobject/flexible][internal-api-flexible]-based tests using [Puppeteer][external-puppeteer].
 
 ## Installation
 
@@ -22,7 +22,7 @@ Built by (c) Clemens Akens. Released under the terms of the [MIT License][intern
 [badge-npm-link]: https://yarnpkg.com/en/package/@pageobject/flexible-puppeteer
 [badge-travis-image]: https://travis-ci.org/clebert/pageobject.svg?branch=master
 [badge-travis-link]: https://travis-ci.org/clebert/pageobject
+[internal-api-flexible]: https://pageobject.js.org/api/flexible/
 [internal-api-flexible-puppeteer]: https://pageobject.js.org/api/flexible-puppeteer/
 [internal-license]: https://github.com/clebert/pageobject/blob/master/LICENSE
-[internal-readme-flexible]: https://github.com/clebert/pageobject/tree/master/@pageobject/flexible/README.md
 [external-puppeteer]: https://github.com/GoogleChrome/puppeteer/blob/master/README.md

@pageobject/flexible-selenium/README.md

@@ -1,6 +1,6 @@
 # @pageobject/flexible-selenium [![Package Version][badge-npm-image]][badge-npm-link] [![Build Status][badge-travis-image]][badge-travis-link] [![Coverage Status][badge-coveralls-image]][badge-coveralls-link]
 
-> Run your [@pageobject/flexible][internal-readme-flexible]-based tests using [Selenium][external-selenium].
+> Run your [@pageobject/flexible][internal-api-flexible]-based tests using [Selenium][external-selenium].
 
 ## Installation
 
@@ -22,7 +22,7 @@ Built by (c) Clemens Akens. Released under the terms of the [MIT License][intern
 [badge-npm-link]: https://yarnpkg.com/en/package/@pageobject/flexible-selenium
 [badge-travis-image]: https://travis-ci.org/clebert/pageobject.svg?branch=master
 [badge-travis-link]: https://travis-ci.org/clebert/pageobject
+[internal-api-flexible]: https://pageobject.js.org/api/flexible/
 [internal-api-flexible-selenium]: https://pageobject.js.org/api/flexible-selenium/
 [internal-license]: https://github.com/clebert/pageobject/blob/master/LICENSE
-[internal-readme-flexible]: https://github.com/clebert/pageobject/tree/master/@pageobject/flexible/README.md
 [external-selenium]: http://seleniumhq.github.io/selenium/docs/api/javascript/index.html

@pageobject/flexible/README.md

@@ -1,6 +1,6 @@
 # @pageobject/flexible [![Package Version][badge-npm-image]][badge-npm-link] [![Build Status][badge-travis-image]][badge-travis-link] [![Coverage Status][badge-coveralls-image]][badge-coveralls-link]
 
-> Write **flexible** tests using a [@pageobject/stable][internal-readme-stable]-based API which is adaptable for different browser automation frameworks.
+> Write **flexible** tests using a [@pageobject/stable][internal-api-stable]-based API which is adaptable for different browser automation frameworks.
 
 ## Installation
 
@@ -23,5 +23,5 @@ Built by (c) Clemens Akens. Released under the terms of the [MIT License][intern
 [badge-travis-image]: https://travis-ci.org/clebert/pageobject.svg?branch=master
 [badge-travis-link]: https://travis-ci.org/clebert/pageobject
 [internal-api-flexible]: https://pageobject.js.org/api/flexible/
+[internal-api-stable]: https://pageobject.js.org/api/stable/
 [internal-license]: https://github.com/clebert/pageobject/blob/master/LICENSE
-[internal-readme-stable]: https://github.com/clebert/pageobject/tree/master/@pageobject/stable/README.md

@pageobject/flexible/src/FlexiblePageObject.ts

@@ -232,6 +232,9 @@ export abstract class FlexiblePageObject extends PageObject<
     );
   }
 
+  /**
+   * This page object is considered visible if its corresponding DOM element consumes space in the document.
+   */
   public isVisible(operator: Operator<boolean> = equals(true)): Condition {
     return new Condition(
       operator,

Makefile

@@ -2,7 +2,7 @@ BIN := "$(shell yarn bin)"
 PKGS := reliable stable flexible flexible-protractor flexible-puppeteer flexible-selenium
 
 .PHONY: docs
-docs: $(addprefix docs/api/,$(PKGS))
+docs: $(addprefix docs/api/,$(PKGS)) docs/index.md
 
 .PHONY: dist
 dist: $(patsubst %,@pageobject/%/dist,$(PKGS))
@@ -16,12 +16,15 @@ clean:
 	$(BIN)/tsc --project @pageobject/$*
 	touch $@
 
-docs/api/%: @pageobject/%/src/*.ts | dist
+docs/api/%: @pageobject/%/README.md @pageobject/%/src/*.ts | dist
 	rm -rf $@
 	rm -rf node_modules/@types/lodash
-	$(BIN)/typedoc --out $@ ./@pageobject/$*
+	$(BIN)/typedoc --out $@ --readme @pageobject/$*/README.md ./@pageobject/$*
 	$(BIN)/replace-in-file '/Defined in .+node_modules./g' 'Defined in ' 'docs/api/$*/**/*.html' --isRegex --verbose
 
+docs/index.md: README.md
+	cp $< $@
+
 node_modules: package.json @pageobject/*/package.json
 	yarn install --check-files
 	touch $@

README.md

@@ -2,46 +2,62 @@
 
 > **Reliable**, **stable**, and **flexible** web UI testing.
 
-## Packages
+## Getting started
 
-This is a multi-package repository ([monorepo][external-monorepo]).
+In this example we navigate to [example.com][external-example-domain] and assert that the page title equals "Example Domain".
 
-### @pageobject/reliable
+```js
+class Page extends FlexiblePageObject {
+  get selector() {
+    return ':root'; // https://developer.mozilla.org/en-US/docs/Web/CSS/:root
+  }
+}
 
-**[Installation][internal-installation-reliable] | [API][internal-api-reliable]**
+function describe(testCase, page) {
+  testCase
+    .perform(page.navigateTo('http://example.com/'))
+    .assert(page.getPageTitle(equals('Example Domain')));
+}
+```
 
-Write **reliable** tests in a declarative programming style.
+_You can find the complete code for this example [here][internal-example-code-getting-started]._
+_It can be executed with Node.js 8 or higher._
 
-### @pageobject/stable
+## API documentation
 
-**[Installation][internal-installation-stable] | [API][internal-api-stable]**
+### [@pageobject/reliable][internal-api-reliable]
 
-Write **stable** tests using a sophisticated implementation of the [page object pattern][external-pageobject].
+Write **reliable** tests in a declarative programming style.
 
-### @pageobject/flexible
+### [@pageobject/stable][internal-api-stable]
 
-**[Installation][internal-installation-flexible] | [API][internal-api-flexible]**
+Write **stable** tests using a sophisticated implementation of the [page object pattern][external-pageobject].
 
-Write **flexible** tests using a @pageobject/stable-based API which is adaptable for different browser automation frameworks.
+### [@pageobject/flexible][internal-api-flexible]
 
-### @pageobject/flexible-protractor
+Write **flexible** tests using a @pageobject/stable-based API which is adaptable for different browser automation frameworks.
 
-**[Installation][internal-installation-flexible-protractor] | [API][internal-api-flexible-protractor]**
+### [@pageobject/flexible-protractor][internal-api-flexible-protractor]
 
 Run your @pageobject/flexible-based tests using [Protractor][external-protractor].
 
-### @pageobject/flexible-puppeteer
-
-**[Installation][internal-installation-flexible-puppeteer] | [API][internal-api-flexible-puppeteer]**
+### [@pageobject/flexible-puppeteer][internal-api-flexible-puppeteer]
 
 Run your @pageobject/flexible-based tests using [Puppeteer][external-puppeteer].
 
-### @pageobject/flexible-selenium
-
-**[Installation][internal-installation-flexible-selenium] | [API][internal-api-flexible-selenium]**
+### [@pageobject/flexible-selenium][internal-api-flexible-selenium]
 
 Run your @pageobject/flexible-based tests using [Selenium][external-selenium].
 
+## Tutorial: TodoMVC
+
+In this tutorial we write a test case for the TodoMVC application.
+We will create several page objects and learn about different design principles.
+
+**You can find the step-by-step instructions [here][internal-example-docs-todo-mvc].**
+
+![todo-mvc][internal-example-image-todo-mvc]
+
 ---
 
 Built by (c) Clemens Akens. Released under the terms of the [MIT License][internal-license].
@@ -58,14 +74,11 @@ Built by (c) Clemens Akens. Released under the terms of the [MIT License][intern
 [internal-api-flexible-selenium]: https://pageobject.js.org/api/flexible-selenium/
 [internal-api-reliable]: https://pageobject.js.org/api/reliable/
 [internal-api-stable]: https://pageobject.js.org/api/stable/
-[internal-installation-flexible]: https://github.com/clebert/pageobject/tree/master/@pageobject/flexible/README.md#installation
-[internal-installation-flexible-protractor]: https://github.com/clebert/pageobject/tree/master/@pageobject/flexible-protractor/README.md#installation
-[internal-installation-flexible-puppeteer]: https://github.com/clebert/pageobject/tree/master/@pageobject/flexible-puppeteer/README.md#installation
-[internal-installation-flexible-selenium]: https://github.com/clebert/pageobject/tree/master/@pageobject/flexible-selenium/README.md#installation
-[internal-installation-reliable]: https://github.com/clebert/pageobject/tree/master/@pageobject/reliable/README.md#installation
-[internal-installation-stable]: https://github.com/clebert/pageobject/tree/master/@pageobject/stable/README.md#installation
+[internal-example-code-getting-started]: https://github.com/clebert/pageobject/tree/master/docs/examples/getting-started/index.js
+[internal-example-docs-todo-mvc]: https://pageobject.js.org/examples/todo-mvc/images/todo-mvc.png
+[internal-example-image-todo-mvc]: https://pageobject.js.org/examples/todo-mvc/
 [internal-license]: https://github.com/clebert/pageobject/blob/master/LICENSE
-[external-monorepo]: https://github.com/lerna/lerna#about
+[external-example-domain]: http://example.com/
 [external-pageobject]: https://martinfowler.com/bliki/PageObject.html
 [external-protractor]: https://www.protractortest.org/#/
 [external-puppeteer]: https://github.com/GoogleChrome/puppeteer/blob/master/README.md