As part of an effort to make it clearer how the client uses Angular,
register UI components with `component()` instead of `directive()`.

Components in Angular 1.x [1] are essentially directives with "best
practices" defaults set (restricted to elements, isolated scope, bound
to controller) and deprecated/discouraged features of $compile
disallowed. These defaults/restrictions match how we are already using
Angular for most UI components.

[1] See https://docs.angularjs.org/guide/component

Correct the title of the documentation

Flesh out the docs for building the docs

Fix client failing to load on pages that define `self`

Make these more user friendly and helpful, less knowledge assumed, but
still very terse.

Update README

Add embedding label

This is so the h docs can cross-ref to this page using intersphinx.

Now that this git repo has Sphinx docs published at
http://h.readthedocs.io/projects/client/, the README should link to
those.

I also reworded a bit to make it more similar to the intro in the Sphinx
docs.

Reorganise docs

Change the docs directory (which was just a directory of markdown files)
to a reStructuredText / Sphinx project.

Docs are reorganized by audience.

Some docs (for example embedding.rst) are copied over from the h repo's
docs. These will be removed from the h repo after this commit is merged.

These are documentation files intended for publishers who're embedding h
in their sites, they're being removed from the h repo into this client
repo.

There may be some reStructuredText syntax in these files that doesn't
work on GitHub (only in Sphinx or only on readthedocs) but these client
docs are about to be moved over to Sphinx/readthedocs anyway.

Keep all the docs for publishers (i.e. people who run websites that
publish content, and want to embed the h client into their site)
together in one docs/publishers folder.

Edit assetRoot and sidebarAppUrl docs

Fix client failing to load on pages that define `self` to be something
other than `window`.

When AnnotatorJS is bundled by browserify, it is first processed by
browserify-shim* which adds references to a variable called 'global',
which exists in Node but not the browser. Browserify then processes the
result and assigns `global` to the value of the first variable from
['global', 'self', 'window'] which is already defined.

https://github.com/hypothesis/h/pull/3385 fixed the problem when the
page defines a variable called 'global' that is not an alias for
'window' by reducing this list to ['self', 'window']. This still leaves
pages that define 'self'.

This commit fixes the problem by always making `global` (within CommonJS
modules) always be assigned the value of `window`.

* browserify-shim deals with the fact that AnnotatorJS 1.2.x is not a
CommonJS module and exports its entry point as `window.Annotator`.

- Clarify that if any service is specified it's used _instead of_, not
in addition to, the default hypothes.is service

- Add note that services settings are still experimental

- Edit the text for clarity

I still don't think the `authority` setting is very well described here,
but I think that setting may be going away in the future, so I'm not
going to try and document it better right now.

The `grantToken` setting could still do with much better docs as well.

Move the docs for these two config settings into their own section in
the docs, and note that they're experimental.

Rename the onLogin callback to onLoginRequest

Remove sourcemap link from boot script

The previous regex would have matched any line that happened to contain
the text 'sourceMappingURL'.

The trigger for invoking this callback function is the user requesting
that a login flow be started. In other words, at the point this callback
is invoked, a login has not occurred, and indeed may never occur if the
user does not complete the login flow.

As such, it seems clearer to have this callback called "onLoginRequest"
rather than "onLogin."

Fixes #274.

Add docs for on login

"Keys" here is programmer jargon, and hopefully the client configuration
documented on this page should be usable by people who aren't
programmers.

config.md was interchangeably using "sidebar" and "client" to refer to
the client. Fix it to always use "client" because it's more consistent.
I chose client instead of sidebar because (both technically speaking and
in terms of the UI) not all of these settings actually refer to the
sidebar, e.g. showHighlights and assetRoot. Also client is the word used
by the git repo name and in the README file.

For example "Client behavior" was a sibling heading of "Config keys",
not a sub heading as intended. Fix all the heading levels so that
headings are nested as they were intended to be.