Commit 18e225cd authored by Robert Knight's avatar Robert Knight Committed by GitHub

Merge pull request #268 from hypothesis/developing-docs-tweaks

Developing docs tweaks
parents 97a95bed 3ed8a159
...@@ -7,27 +7,40 @@ Hypothesis is comprised of several components: ...@@ -7,27 +7,40 @@ Hypothesis is comprised of several components:
the client uses the public service at [hypothes.is](https://hypothes.is). the client uses the public service at [hypothes.is](https://hypothes.is).
- A browser extension which can add the client to web pages. - A browser extension which can add the client to web pages.
In order to develop the client and test out changes you make locally, you will ## Prerequisites
need to use either the [browser
extension](https://github.com/hypothesis/browser-extension) or setup a [a local
install of the Hypothesis
service](http://h.readthedocs.io/en/latest/developing/) to host the client.
If you are only interested in making changes to the client, developing using You will need:
the browser extension is the easiest method.
## Prerequisites and Installation * [git](https://git-scm.com/)
* [Node.js](https://nodejs.org/en/) v6+
To develop the client, you will need [Node.js v6](https://nodejs.org/en/) or ## Building
later and [gulp](https://github.com/gulpjs/gulp-cli). To install dependencies
run: To build the client for development:
```sh ```sh
npm install -g gulp-cli 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
``` ```
## Developing using the browser extension 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.
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
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 1. Check out the [browser
extension](https://github.com/hypothesis/browser-extension) and follow the extension](https://github.com/hypothesis/browser-extension) and follow the
...@@ -36,6 +49,7 @@ make ...@@ -36,6 +49,7 @@ make
to make it use your local version of the client and the [production to make it use your local version of the client and the [production
Hypothesis Hypothesis
service](https://github.com/hypothesis/browser-extension/blob/master/docs/building.md). service](https://github.com/hypothesis/browser-extension/blob/master/docs/building.md).
1. Start the client's development server to rebuild the client whenever it 1. Start the client's development server to rebuild the client whenever it
changes: changes:
...@@ -49,13 +63,18 @@ make ...@@ -49,13 +63,18 @@ make
Reloader](https://chrome.google.com/webstore/detail/extensions-reloader/fimgfedafeadlieiabdeeaodndnlbhid?hl=en) Reloader](https://chrome.google.com/webstore/detail/extensions-reloader/fimgfedafeadlieiabdeeaodndnlbhid?hl=en)
to make this easier. to make this easier.
If you want to use the browser extension together with a local Hypothesis ## Running the client from the web service
service for storing annotations, you should also follow the steps below.
## Developing using a local Hypothesis web service This takes longer to setup than
[Running the client from the browser extension](#running-the-client-from-the-browser-extension).
You should follow these steps if you want to make changes to the Hypothesis
web service as well as to the client.
Once you have a local install of the Hypothesis service set up, you can First follow the [instructions for setting up a development install of the web
configure it to use a local build of the client. In the client repository, run: 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 ```sh
export H_SERVICE_URL=http://localhost:5000 export H_SERVICE_URL=http://localhost:5000
...@@ -65,7 +84,7 @@ gulp watch ...@@ -65,7 +84,7 @@ gulp watch
The `H_SERVICE_URL` env var sets the URL of the service which hosts the HTML The `H_SERVICE_URL` env var sets the URL of the service which hosts the HTML
entry point for the client's sidebar application. entry point for the client's sidebar application.
In the `hypothesis/h` repository, set the `CLIENT_URL` env var to tell the **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`: service where to load the client from, before running `make dev`:
```sh ```sh
...@@ -83,7 +102,7 @@ You can also load the client into your own web pages by adding: ...@@ -83,7 +102,7 @@ You can also load the client into your own web pages by adding:
<script async src="http://localhost:5000/embed.js"></script> <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 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 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. the client into a browser extension is the easiest option.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment