Merge pull request #279 from hypothesis/reorganise-docs

Reorganise docs

.gitignore

 build/
 node_modules/
 coverage/
+docs/_build/

Makefile

@@ -19,6 +19,10 @@ test: node_modules/.uptodate
 lint: node_modules/.uptodate
 	npm run lint
 
+.PHONY: docs
+docs:
+	cd docs && make livehtml
+
 ################################################################################
 
 build/manifest.json: node_modules/.uptodate

docs/Makefile

+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = HypothesisClient
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+livehtml:
+	sphinx-autobuild -b dirhtml -p 8888 "$(SOURCEDIR)" "$(BUILDDIR)/dirhtml" $(SPHINXOPTS) $(O)
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/screenshot.png

+../../images/screenshot.png
\ No newline at end of file

docs/conf.py

+# -*- coding: utf-8 -*-
+#
+# Hypothesis Client documentation build configuration file, created by
+# sphinx-quickstart on Thu Mar  9 18:01:59 2017.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import os
+# import sys
+
+from recommonmark.parser import CommonMarkParser
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# sys.path.insert(0, os.path.abspath('.'))
+
+# on_rtd is whether the docs are being built on readthedocs.org (or whether
+# someone is building them locally), this line of code grabbed from
+# docs.readthedocs.org
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.todo', 'sphinx.ext.intersphinx']
+
+intersphinx_mapping = {'h': ('https://h.readthedocs.io/en/latest/', None)}
+
+# Add any paths that contain tempates here, relative to this directory.
+templates_path = ['_templates']
+
+source_parsers = {
+    '.md': CommonMarkParser,  # Add Markdown support to Sphinx.
+}
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = ['.rst', '.md']
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Hypothesis Client'
+copyright = u'2017, Hypothesis Project Contributors'
+author = u'Hypothesis Project Contributors'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = u'1.0.0'
+# The full version, including alpha/beta/rc tags.
+release = u'1.0.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+numfig = True
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# otherwise, readthedocs.org uses their theme by default, so no need to specify it
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+html_theme_options = {
+    'display_version': False,
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'HypothesisClientdoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'HypothesisClient.tex', u'Hypothesis Client Documentation',
+     u'Hypothesis Project Contributors', 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'hypothesisclient', u'Hypothesis Client Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'HypothesisClient', u'Hypothesis Client Documentation',
+     author, 'HypothesisClient', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+

docs/config.md

-Configuring the client
-======================
-
-### Configuring the client using JSON
-
-The Hypothesis client can be configured by providing a JSON config object in
-the body of the hosting page:
-
-```html
-<script type="application/json" class="js-hypothesis-config">
-  {
-    "openSidebar": true
-  }
-</script>
-<script async src="https://hypothes.is/embed.js"></script>
-```
-
-Not all configuration settings can be set in this way, some must be
-[set using JavaScript](#configuring-the-client-using-javascript) (see below).
-
-**N.B.** The body of the `.js-hypothesis-config` tag must be [valid
-JSON](http://jsonlint.com/) -- invalid JSON will cause the entire config object
-to be ignored.
-
-### Configuring the client using JavaScript
-
-Alternatively, the Hypothesis client can be configured from the hosting page by
-providing a JavaScript function named `window.hypothesisConfig` that returns
-a configuration object. Some configuration settings (for example settings that
-register callback or event handler functions) can _only_ be set from
-JavaScript:
-
-```html
-window.hypothesisConfig = function () {
-  return {
-    "openSidebar": true
-  };
-};
-```
-
-Config settings
----------------
-
-### Client behavior
-
-These settings configure the behavior and initial state of the client when it
-loads.
-
-#### `openLoginForm`
-
-_Boolean_. Controls whether the login panel is automatically opened on startup,
-as if the user had clicked "Log in" themselves. (Default: _false_.)
-
-#### `openSidebar`
-
-_Boolean_. Controls whether the sidebar opens automatically on startup.
-(Default: _false_.)
-
-#### `showHighlights`
-
-_Boolean_. Controls whether the in-document highlights are shown by default.
-(Default: _true_.)
-
-### Annotation services
-
-The `services` setting configures which annotation services the client
-connects to (for example to login, retrieve annotations, and save annotations).
-By default, if no `services` setting is given, the client connects to the
-public Hypothesis service at [hypothes.is](https://hypothes.is).
-
-#### `services`
-
-_Array_. A list of alternative annotation services which the client should
-connect to instead of connecting the the public Hypothesis service at
-[hypothes.is](https://hypothes.is/).
-May optionally include information (in the form of a grant token) about the
-identity of the user accounts that the client is logged in to on those
-services.
-
-**N.B.** These settings are currently still experimental and may change without
-warning.
-
-**N.B.** Currently only one alternative annotation service at a time is
-supported - only the first item in this `services` array is used, and any
-further items in the array are ignored.
-
-Each item in the `services` array should be an object describing an annotation
-service, with the following keys:
-
- * `authority` _String_. The domain name which the annotation service is
-   associated with.
-
- * `grantToken` _String|null_. An OAuth 2 grant token which the client can
-   exchange for an access token in order to make authenticated requests to the
-   service. If _null_, the user will be able to read but not create or modify
-   annotations. (Default: _null_)
-
- * `icon` _String|null_. The URL to an image for the annotation service. This
-   image will appear to the left of the name of the currently selected group.
-   The image should be suitable for display at 16x16px and the recommended
-   format is SVG.
-
- * `onLoginRequest` _function_. A JavaScript function that the client will
-   call in order to login (for example, when the user clicks a login button in
-   the Hypothesis client's sidebar).
-
-   This setting can only be [set using window.hypothesisConfig](#configuring-the-client-using-javascript).
-
-   If the hosting page provides an `onLoginRequest` function then the Hypothesis
-   client will call this function instead of doing its usual procedure for
-   logging in to the public service at [hypothes.is](https://hypothes.is/).
-
-   No arguments are passed to the `onLoginRequest` function.
-
-   The `onLoginRequest` function should cause a login procedure for the hosting page
-   to be performed - for example by redirecting to a login page, or by opening
-   a popup login window. After a successful login the hosting page should
-   reload the original page with a non-null `grantToken` for the logged-in user
-   in the `services` configuration setting.
-
-### Asset and sidebar app location
-
-These settings configure where the client's assets are loaded from.
-
-**N.B.** These settings are currently still experimental and may change without
-warning.
-
-#### `assetRoot`
-
-_String_. The root URL from which assets are loaded. This should be set to the
-URL where the contents of the `hypothesis` package are hosted, including the
-trailing slash. (Default: For production builds:
-_https://cdn.hypothes.is/hypothesis/X.Y.Z/_, for development builds:
-_http://localhost:3001/hypothesis/X.Y.Z/_. _X.Y.Z_ is the package version from
-`package.json`)
-
-#### `sidebarAppUrl`
-
-_String_. The URL for the sidebar application which displays annotations
-(Default: _https://hypothes.is/app.html_ . If the `H_SERVICE_URL` env var is
-set, defaults to `${H_SERVICE_URL}/app.html`)

docs/developing.md → docs/developers/developing.rst

-# Developing the client
+Developing the Client
+=====================
 
-Hypothesis is comprised of several components:
+This section documents how to setup a development environment for the client,
+how to run the client and its tests in a development environment,
+client coding standards and how to contribute code to the client.
 
- - A browser-based web app for annotating web pages (this repository)
- - A service which stores annotations, user accounts and other data. By default
-   the client uses the public service at [hypothes.is](https://hypothes.is).
- - A browser extension which can add the client to web pages.
+Setting up a Client Development Environment
+-------------------------------------------
 
-## Prerequisites
+Prerequisites
+#############
 
 You will need:
 
-* [git](https://git-scm.com/)
-* [Node.js](https://nodejs.org/en/) v6+
+* `git <https://git-scm.com/>`_
+* `Node.js <https://nodejs.org/en/>`_ v6+
 
-## Building
+Building
+########
 
 To build the client for development:
 
-```sh
-git clone 'https://github.com/hypothesis/client.git'
-cd client
-npm install -g gulp-cli  # Tip: if you get a "permission denied" error try
+.. code-block:: sh
+
+   git clone 'https://github.com/hypothesis/client.git'
+   cd client
+   npm install -g gulp-cli  # Tip: if you get a "permission denied" error try
                             # `sudo npm install -g gulp-cli` instead.
-make
-```
+   make
 
 You now have a development client built. To run your development client in
 a browser you'll need a local copy of either the Hypothesis Chrome extension or
-the Hypothesis web service. Follow either the instructions for
-[Running the client from the browser extension](#running-the-client-from-the-browser-extension)
-or for
-[Running the client from the web service](#running-the-client-from-the-web-service)
-below.
+the Hypothesis web service. Follow either
+:ref:`running-from-browser-ext` or :ref:`running-from-web-service` below.
 If you're only interested in making changes to the client (and not to the web
 service) then running the client from the browser extension is easiest.
 
-## Running the client from the browser extension
+
+.. _running-from-browser-ext:
+
+Running the Client from the Browser Extension
+---------------------------------------------
 
 This is the currently easiest way to get your development client running in a
 browser. It sets you up to make changes to the client and to the Chrome
 extension itself, but not to the web service.
 
-1. Check out the [browser
-   extension](https://github.com/hypothesis/browser-extension) and follow the
-   steps in the
-   [README](https://github.com/hypothesis/browser-extension/blob/master/README.md)
-   to make it use your local version of the client and the [production
-   Hypothesis
-   service](https://github.com/hypothesis/browser-extension/blob/master/docs/building.md).
+#. Check out the
+   `browser extension <https://github.com/hypothesis/browser-extension>`_
+   and follow the steps in the browser extension's documentation to build the
+   extension and configure it to use your local version of the client and the
+   production Hypothesis service.
 
-1. Start the client's development server to rebuild the client whenever it
+#. Start the client's development server to rebuild the client whenever it
    changes:
 
-    ```
+    .. code-block:: sh
+
        gulp watch
-    ```
 
-1. After making changes to the client, you will need to run `make` in the
+#. After making changes to the client, you will need to run ``make`` in the
    browser extension repo and reload the extension in Chrome to see changes.
-   You can use [Extensions
-   Reloader](https://chrome.google.com/webstore/detail/extensions-reloader/fimgfedafeadlieiabdeeaodndnlbhid?hl=en)
+   You can use
+   `Extensions Reloader <https://chrome.google.com/webstore/detail/extensions-reloader/fimgfedafeadlieiabdeeaodndnlbhid?hl=en>`_
    to make this easier.
 
-## Running the client from the web service
+.. _running-from-web-service:
+
+Running the Client From the Web Service
+---------------------------------------
 
-This takes longer to setup than
-[Running the client from the browser extension](#running-the-client-from-the-browser-extension).
+This takes longer to setup than :ref:`running-from-browser-ext`.
 You should follow these steps if you want to make changes to the Hypothesis
 web service as well as to the client.
 
-First follow the [instructions for setting up a development install of the web
-service](http://h.readthedocs.io/en/latest/developing/).
+First follow the
+`instructions for setting up a development install of the web service <http://h.readthedocs.io/en/latest/developing/>`_.
 Once you have a development install of the Hypothesis service set up, you can
 configure it to use a local build of the client. **In the client repository**,
 run:
 
-```sh
-export H_SERVICE_URL=http://localhost:5000
-gulp watch
-```
+.. code-block:: sh
 
-The `H_SERVICE_URL` env var sets the URL of the service which hosts the HTML
-entry point for the client's sidebar application.
+   export H_SERVICE_URL=http://localhost:5000
+   gulp watch
 
-**In the `hypothesis/h` repository**, set the `CLIENT_URL` env var to tell the
-service where to load the client from, before running `make dev`:
+**In the `hypothesis/h` repository**, set the :envvar:`CLIENT_URL` env var to
+tell the service where to load the client from, before running ``make dev``:
 
-```sh
-export CLIENT_URL=http://localhost:3001/hypothesis
-make dev
-```
+.. code-block:: sh
+
+   export CLIENT_URL=http://localhost:3001/hypothesis
+   make dev
 
 Once the client and service are running, you can test it out by visiting:
-[http://localhost:3000](http://localhost:3000) or [the Help
-page](http://localhost:5000/docs/help) in your browser.
+http://localhost:3000 or http://localhost:5000/docs/help in your browser.
 
 You can also load the client into your own web pages by adding:
 
-```html
-<script async src="http://localhost:5000/embed.js"></script>
-```
+.. code-block:: html
+
+   <script async src="http://localhost:5000/embed.js"></script>
 
 to the page's HTML. Note that this will only work in pages served via plain
 HTTP.  If you want to test out the client on pages served via HTTPS then building
 the client into a browser extension is the easiest option.
 
-## Running tests
+Running the Tests
+-----------------
 
 Hypothesis uses Karma and mocha for testing. To run all the tests once, run:
 
-```sh
-gulp test
-```
+.. code-block:: sh
+
+   gulp test
 
 To run tests and automatically re-run them whenever any source files change, run:
 
-```sh
-gulp test-watch
-```
+.. code-block:: sh
 
-You can filter the tests which are run by passing `--grep <pattern>` as an
-argument to `gulp test`. See the documentation for Mocha's
-[grep](https://mochajs.org/#g---grep-pattern) option.
+   gulp test-watch
 
+You can filter the tests which are run by passing ``--grep <pattern>`` as an
+argument to ``gulp test``. See the documentation for Mocha's
+`grep <https://mochajs.org/#g---grep-pattern>`_ option.
 
-## Code style
+Code Style
+----------
 
-### JavaScript
+JavaScript
+##########
 
 Hypothesis uses ESLint to help maintain style consistency. You can check your
 changes for conformance using:
 
-```
-make lint
-```
+.. code-block:: sh
+
+   make lint
 
 Many lint errors can be fixed automatically using:
 
-```
-./node_modules/.bin/eslint --fix
-```
+.. code-block:: sh
+
+   ./node_modules/.bin/eslint --fix
 
-### CSS
+CSS
+###
 
 Styling is authored in SASS. For guidance on writing CSS for Hypothesis
-projects, please see our [CSS
-Guide](https://github.com/hypothesis/frontend-toolkit/blob/master/docs/css-style-guide.md).
+projects, please see our
+`CSS Guide <https://github.com/hypothesis/frontend-toolkit/blob/master/docs/css-style-guide.md>`_.
 
-## Submitting pull requests
+Submitting Pull Requests
+------------------------
 
 For general guidance on submitting pull requests to Hypothesis projects, please
-see the [Contributor's Guide](https://h.readthedocs.io/en/latest/developing/).
+see the `Contributor's Guide <https://h.readthedocs.io/en/latest/developing/>`_.

docs/developers/envvars.rst

+Environment Variables
+=====================
+
+This section documents all the environment variables supported by the client's
+build tasks.
+
+.. envvar:: H_SERVICE_URL
+
+   The URL of the service which hosts the HTML entry point for the client's
+   sidebar application.

docs/developers/index.rst

+For Developers
+==============
+
+This section contains documentation for **developers** contributing code to
+the Hypothesis client.
+
+.. toctree::
+   :maxdepth: 3
+
+   developing
+   security
+   envvars

docs/documenters/buildthedocs.rst

+Building the Docs Locally
+=========================
+
+You will need:
+
+#. Git
+#. Python and Virtualenv
+#. Make
+
+To build the docs:
+
+#. ``git clone https://github.com/hypothesis/client.git``
+#. ``cd client``
+#. Create and activate a Python virtual environment.
+#. ``pip install -r requirements-dev.in``
+#. ``make docs``
+
+Now open http://localhost:8888 to view your local build of the docs.
+The built docs will automatically update when you save changes to the source
+files.

docs/documenters/index.rst

+For Documenters
+===============
+
+This section contains documentation for **documenters** who want to contribute
+documentation to the Hypothesis client.
+
+.. toctree::
+   :maxdepth: 3
+
+   buildthedocs

docs/host-page-integration.md

-# Interacting with the sidebar
-
-## Show the sidebar:
-
-If you need to have a custom trigger on your third party page to bring up the embedded Hypothesis
-sidebar, add the `data-hypothesis-trigger` attribute to the element that you want to enable.
-Clicking that element will cause the sidebar to open.
-Note, however, subsequent clicks do not hide the sidebar.
-
-Example:
-
-To add a `button` on a page to open the sidebar, simply
-add the `data-hypothesis-trigger` attribute.
-
-```html
-<button data-hypothesis-trigger>
-  Open sidebar
-</button>
-```
-
-## Show the public annotation count:
-
-If you need to show the total number of public annotations, page notes and orphaned annotations
-on your third party page where the Hypothesis sidebar is embedded, add the `data-hypothesis-annotation-count`
-attribute to the element that you want to enable.
-The contents of the enabled element will be replaced with the count of public annotations and if there are no
-public annotations, with 0.
-
-Example:
-
-To display the annotation count in a `div` element, simply
-add the `data-hypothesis-annotation-count` attribute to the `div`:
-
-```html
-<div data-hypothesis-annotation-count>
-  Annotation count will appear here
-</div>
-```

docs/index.rst

+Welcome to Hypothesis Client's documentation!
+=============================================
+
+The `Hypothesis client <https://github.com/hypothesis/client>`_ is a browser-based tool for making annotations on web
+pages. It's a client for the `Hypothesis web annotation service <http://h.readthedocs.io/>`_.
+It's used by the
+`Hypothesis browser extension <https://chrome.google.com/webstore/detail/hypothesis-web-pdf-annota/bjfhmglciegochdpefhhlphglcehbmek>`_, and can also be
+:doc:`embedded directly into web pages <publishers/embedding>`.
+
+.. image:: /_static/screenshot.png
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   publishers/index
+   developers/index
+   documenters/index

docs/publishers/config.rst

+Configuring the Client
+======================
+
+This page documents the configuration settings that you can use to configure
+the Hypothesis client once it's embedded in your website.
+
+Configuring the Client Using JSON
+---------------------------------
+
+The Hypothesis client can be configured by providing a JSON config object in
+the body of the hosting page:
+
+.. code-block:: html
+
+   <script type="application/json" class="js-hypothesis-config">
+     {
+       "openSidebar": true
+     }
+   </script>
+   <script async src="https://hypothes.is/embed.js"></script>
+
+Not all configuration settings can be set in this way, some must be
+:ref:`set using JavaScript <configuring-with-js>` (see below).
+
+.. note::
+
+   The body of the ``.js-hypothesis-config`` tag must be
+   `valid JSON <http://jsonlint.com/>`_, invalid JSON will cause the entire
+   config object to be ignored.
+
+.. _configuring-with-js:
+
+Configuring the Client Using JavaScript
+---------------------------------------
+
+.. js:function:: window.hypothesisConfig()
+
+   Alternatively, the Hypothesis client can be configured from the hosting page
+   by providing a JavaScript function named :js:func:`window.hypothesisConfig`
+   that returns a configuration object. Some configuration settings (for
+   example settings that register callback or event handler functions) can
+   *only* be set from JavaScript:
+
+   .. code-block:: javascript
+
+      window.hypothesisConfig = function () {
+        return {
+          "openSidebar": true
+        };
+      };
+
+Config Settings
+---------------
+
+Client Behavior
+###############
+
+These settings configure the behavior and initial state of the client when it
+loads.
+
+.. option:: openLoginForm
+
+   ``Boolean``. Controls whether the login panel is automatically opened on
+   startup, as if the user had clicked "Log in" themselves.
+   (Default: ``false``.)
+
+.. option:: openSidebar
+
+   ``Boolean``. Controls whether the sidebar opens automatically on startup.
+   (Default: ``false``.)
+
+.. option:: showHighlights
+
+   ``Boolean``. Controls whether the in-document highlights are shown by default.
+   (Default: ``true``.)
+
+.. option:: services
+
+   ``Array``. A list of alternative annotation services which the client should
+   connect to instead of connecting to the public Hypothesis service at
+   `hypothes.is <https://hypothes.is/>`_. May optionally include information
+   (in the form of grant tokens) about user accounts that the client is logged
+   in to on those services.
+
+   For example:
+
+   .. code-block:: javascript
+
+      window.hypothesisConfig = function () {
+        return {
+          services: [{
+            authority: 'partner.org',
+            grantToken: '***',
+            icon: 'https://openclipart.org/download/272629/sihouette-animaux-10.svg'
+          }],
+        };
+      };
+
+   By default, if no :option:`services` setting is given, the client connects
+   to the public Hypothesis service at `hypothes.is <https://hypothes.is/>`_.
+
+   .. warning::
+
+      The :option:`services` setting is currently still experimental and may
+      change in the future.
+
+   .. note::
+
+      Currently only one additional annotation service is supported - only the
+      first item in this :option:`services` array is used, and any further
+      items in the array are ignored.
+
+   Each item in the :option:`services` array should be an object describing an
+   annotation service, with the following keys:
+
+   .. option:: authority
+   
+      ``String``. The domain name which the annotation service is associated with.
+
+   .. option:: grantToken
+   
+      ``String|null``. An OAuth 2 grant token which the client can send to the
+      service in order to get an access token for making authenticated requests
+      to the service. If ``null``, the user will not be logged in and will only
+      be able to read rather than create or modify annotations. (Default:
+      ``null``)
+
+      .. seealso::
+
+         :ref:`Generating authorization grant tokens` for how to generate grant
+         tokens for the `hypothes.is <https://hypothes.is/>`_ service.
+
+   .. option:: icon
+   
+      ``String|null``. The URL to an image for the annotation service. This
+      image will appear to the left of the name of the currently selected
+      group. The image should be suitable for display at 16x16px and the
+      recommended format is SVG.
+
+   .. option:: onLoginRequest
+   
+     ``function``. A JavaScript function that the Hypothesis client will
+     call in order to login (for example, when the user clicks a login button in
+     the Hypothesis client's sidebar).
+
+     This setting can only be set using :js:func:`window.hypothesisConfig`.
+
+     If the hosting page provides an :option:`onLoginRequest` function then the
+     Hypothesis client will call this function instead of doing its usual
+     procedure for logging in to the public service at `hypothes.is
+     <https://hypothes.is/>`_.
+
+     No arguments are passed to the :option:`onLoginRequest` function.
+
+     The :option:`onLoginRequest` function should cause a login procedure for
+     the hosting page to be performed - for example by redirecting to a login
+     page, or by opening a popup login window. After a successful login the
+     hosting page should reload the original page with a non-null
+     :option:`grantToken` for the logged-in user in the :option:`services`
+     configuration setting.
+
+Asset and Sidebar App Location
+##############################
+
+These settings configure where the client's assets are loaded from.
+
+.. warning::
+
+   These settings are currently still experimental and may change in the future.
+
+.. option:: assetRoot
+
+   ``String``. The root URL from which assets are loaded. This should be set to
+   the URL where the contents of the hypothesis package are hosted, including
+   the trailing slash. (Default: for production builds:
+   ``"https://cdn.hypothes.is/hypothesis/X.Y.Z/"``, for development builds:
+   ``"http://localhost:3001/hypothesis/X.Y.Z/""`.
+   ``X.Y.Z`` is the package version from ``package.json``).
+
+.. option:: sidebarAppUrl
+
+   ``String``. The URL for the sidebar application which displays annotations
+   (Default: ``"https://hypothes.is/app.html"``).

docs/publishers/embedding.rst

+How to Add Hypothesis to Your Website
+=====================================
+
+.. If you update this page, please ensure you update the "For Publishers" page
+   on the Hypothesis website, or coordinate with someone who can
+   (https://hypothes.is/for-publishers/).
+
+To add Hypothesis to your website, just add this one line to the HTML source of
+each page that you want to have the Hypothesis client on:
+
+.. code-block:: html
+
+   <script src="https://hypothes.is/embed.js" async></script>

docs/publishers/host-page-integration.rst

+Interacting with the Client
+===========================
+
+This page documents the ways in which your website can interact with the
+Hypothesis client, once the client is embedded in your site.
+
+.. option:: data-hypothesis-trigger
+
+   You can add a button to your page that opens the Hypothesis sidebar.
+
+   If you need to have a custom trigger on your third party page to bring up
+   the embedded Hypothesis sidebar, add the :option:`data-hypothesis-trigger`
+   attribute to the element that you want to enable.  Clicking that element
+   will cause the sidebar to open.  Note, however, subsequent clicks do not
+   hide the sidebar.
+
+   For example to add a ``<button>`` on a page to open the sidebar, simply
+   add the :option:`data-hypothesis-trigger` attribute:
+
+   .. code-block:: html
+
+      <button data-hypothesis-trigger>
+        Open sidebar
+      </button>
+
+.. option:: data-hypothesis-annotation-count
+
+   You can add a count of the number of annotations to your page.
+
+   If you need to show the total number of public annotations, page notes and
+   orphaned annotations on your third party page where the Hypothesis client
+   is embedded, add the :option:`data-hypothesis-annotation-count` attribute to
+   the element that you want to enable.  The contents of the enabled element
+   will be replaced with the count of public annotations and if there are no
+   public annotations, with 0.
+
+   For example to display the annotation count in a ``<div>`` element, simply
+   add the :option:`data-hypothesis-annotation-count` attribute to the
+   ``<div>``:
+
+   .. code-block:: html
+
+      <div data-hypothesis-annotation-count>
+        Annotation count will appear here
+      </div>

docs/publishers/index.rst

+For Content Publishers
+======================
+
+This section is for **content publishers** who publish content to the web and
+want to integrate the Hypothesis client into their web pages. If you want to
+add the Hypothesis client to your web pages so that visitors can annotate the
+pages without having to install their own Hypothesis browser extension, these
+pages will help you get started.
+
+.. toctree::
+   :maxdepth: 3
+
+   embedding
+   config
+   host-page-integration

requirements-dev.in

+# Python requirements needed to run the `make docs` command.
+recommonmark
+sphinx
+sphinx-autobuild
+sphinx_rtd_theme