Skip to content

Commit e6badb2

Browse files
HironsanHironsan
committed
Add documentation by mkdocs
1 parent f9be910 commit e6badb2

File tree

7 files changed

+402
-9
lines changed

7 files changed

+402
-9
lines changed

‎docs/advanced/aws_https_settings.md

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# HTTPS settings for doccano in AWS
2+
3+
4+
1. Create hosted zone in Route 53
5+
2. Create certificate in ACM
6+
3. Create EC2 instance
7+
4. Create ELB
8+
5. Create A record in Route 53
9+
10+
11+
12+
# Create hosted zone in Route 53
13+
14+
HTTPS need a domain name. If you don't have one, you can register it by the AWS Route 53 service, or you can get one from other domain seller.
15+
16+
After you get a domain name, you can create Hosted Zone by Route 53.
17+
18+
If you register domain from Route 53, you can find it in the `Hosted Zone`.
19+
20+
![2B0FF02C-42DA-41D1-BFA1-31018BE006ED](https://camo.githubusercontent.com/998dab1eca0e9673ab98d92b65b199cb4e2f96ea/68747470733a2f2f7773332e73696e61696d672e636e2f6c617267652f303036744b665463677931673132397a346c3733726a333131783065673078332e6a7067)
21+
22+
23+
24+
# Create certificate in ACM
25+
26+
![22F3520E-909A-4215-B73A-DBB452E3D4E2](https://camo.githubusercontent.com/e3e0a24d2265728072d9e65220a41d2ddd6b42bb/68747470733a2f2f7773322e73696e61696d672e636e2f6c617267652f303036744b6654636779316731326132653362306a6a3331666c3062683433312e6a7067)
27+
28+
You should replace the domain name by yours.
29+
30+
![image-20190314145326046](https://camo.githubusercontent.com/faf83a9ee1774d92a01de9f69e48ed002c7a827e/68747470733a2f2f7773312e73696e61696d672e636e2f6c617267652f303036744b66546367793167313261336a356d33756a333166393066613077342e6a7067)
31+
32+
33+
34+
35+
36+
![image-20190314145344449](https://camo.githubusercontent.com/874362144a3547629383ad93e1f13831e35d0b82/68747470733a2f2f7773312e73696e61696d672e636e2f6c617267652f303036744b665463677931673132613375736232626a33306b6b3039626a73762e6a7067)
37+
38+
39+
40+
![4FC120A2-6DB5-4F03-A209-12C22EDD6097](https://camo.githubusercontent.com/b75bc07e8d96b796872c697de951ab44d74d04d3/68747470733a2f2f7773342e73696e61696d672e636e2f6c617267652f303036744b665463677931673132613873643730786a3331667630686637646d2e6a7067)
41+
42+
43+
44+
Don't forget to Create record in Route 53 in step 4.
45+
46+
After you request a certificate, wait for a while, You should see the status become 'Issued'.
47+
48+
49+
50+
![3AAE20BC-FC34-4738-AED0-D7D67929F6FF](https://camo.githubusercontent.com/82528820652678c19ee46ff5a0f07dbfaba31f5e/68747470733a2f2f7773322e73696e61696d672e636e2f6c617267652f303036744b66546367793167313261356a776270726a333136743066387139622e6a7067)
51+
52+
# Create EC2 instance
53+
54+
In this part, you can just click the launch button to create a EC2 instance.
55+
56+
[![AWS CloudFormation Launch Stack SVG Button](https://cdn.rawgit.com/buildkite/cloudformation-launch-stack-button-svg/master/launch-stack.svg)](https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/create/review?templateURL=https://s3-external-1.amazonaws.com/cf-templates-10vry9l3mp71r-us-east-1/20190732wl-new.templatexloywxxyimi&stackName=doccano)
57+
58+
# Create ELB
59+
60+
![image-20190314150439785](https://camo.githubusercontent.com/158c2fb2957546ed8bb82694497b60b9c7f38aa5/68747470733a2f2f7773332e73696e61696d672e636e2f6c617267652f303036744b6654636779316731326166376a676a746a3330663230337a3734742e6a7067)
61+
62+
Click the `Create Load Balancer` button and select `Application Load Balancer`.
63+
64+
Fill the name, change protocol to HTTPS, and do not forget add at least two availability zones. Make sure the zone that EC2 instance created is included.
65+
66+
![02BE83A7-4C43-48BE-BCF0-95D2DF7C603D](https://camo.githubusercontent.com/c4cc530aea78e66ea99eab905804cae66ab20a04/68747470733a2f2f7773342e73696e61696d672e636e2f6c617267652f303036744b665463677931673132616861756566736a3330796e306d6e6774732e6a7067)
67+
68+
Select the certificate we created early.
69+
70+
![image-20190314151004337](https://camo.githubusercontent.com/455140fc7b7a22a18e96e5f2aa31d9fd0e7c7722/68747470733a2f2f7773312e73696e61696d672e636e2f6c617267652f303036744b665463677931673132616b75693576366a333071763063303431382e6a7067)
71+
72+
You can select the same security groups created when you create the EC2 instance.
73+
74+
![image-20190314151110756](https://camo.githubusercontent.com/5d029d4fa494420ed077be6b57ab60935d378e7f/68747470733a2f2f7773322e73696e61696d672e636e2f6c617267652f303036744b665463677931673132616c7a796735756a33313272306139676f392e6a7067)
75+
76+
Or you can create a new one
77+
78+
![image-20190314151253917](https://camo.githubusercontent.com/e620c6738ff95f3311edf708b80a949f8b79f565/68747470733a2f2f7773312e73696e61696d672e636e2f6c617267652f303036744b665463677931673132616e736d3931706a333163313062646469652e6a7067)
79+
80+
81+
82+
Fill the target group name and leave others defualt.
83+
84+
![image-20190314151314109](https://camo.githubusercontent.com/f22b99c57ca9b8114683f1501942dcc3cc0874f1/68747470733a2f2f7773322e73696e61696d672e636e2f6c617267652f303036744b665463677931673132616f34797661746a3330716630666a74616d2e6a7067)
85+
86+
Add the instance to registered.
87+
88+
![image-20190314151358736](https://camo.githubusercontent.com/515649dce66466e9cefa730fc1a35a398ecb260d/68747470733a2f2f7773322e73696e61696d672e636e2f6c617267652f303036744b665463677931673132616f777667736f6a333136793066346164672e6a7067)
89+
90+
Then review and create.
91+
92+
# Create A record in Route 53
93+
94+
Back to route 53, and click `Create Record Set`. Fill the subname and the ELB name in the `Alias Target`.
95+
96+
![image-20190314151601030](https://camo.githubusercontent.com/82944e13e1ef3f4015484417a50635c9352dae33/68747470733a2f2f7773312e73696e61696d672e636e2f6c617267652f303036744b665463677931673132617231383931666a33306278306e6d6a746d2e6a7067)
97+
98+
Finally, you can access the doccano by HTTPS.
99+
100+
![image-20190314151841872](https://camo.githubusercontent.com/85dfef30b4b01df5e0d8e339b38e5a31592dd103/68747470733a2f2f7773332e73696e61696d672e636e2f6c617267652f303036744b6654636779316731326174746563636b6a3330716730396d6a73612e6a7067)

‎docs/advanced/oauth2_settings.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
This document aims to instruct how to setup OAuth for doccano. doccano now supports social login via GitHub and Active Directory by [#75](https://github.com/chakki-works/doccano/pull/75). In this document, we show GitHub OAuth as an example.
2+
3+
4+
## Create OAuth App
5+
6+
1. In the upper-right corner of GitHub, click your profile photo, then click **Settings**.
7+
2. In the left sidebar, click **Developer settings**.
8+
3. In the left sidebar, click **OAuth Apps**.
9+
4. Click **New OAuth App**.
10+
5. In "Application name", type the name of your app.
11+
6. In "Homepage URL", type the full URL to your app's website.
12+
7. In "Authorization callback URL", type the callback URL(e.g. <https://example.com/social/complete/github/>) of your app.
13+
8. Click Register application.
14+
15+
## Set enviromental variables
16+
17+
Once the application is registered, your app's `Client ID` and `Client Secret` will be displayed on the following page:
18+
![image](https://user-images.githubusercontent.com/6737785/51811605-1073d480-22f1-11e9-8be0-726a8ee5e832.png)
19+
20+
1. Copy the `Client ID` and `Client Secret` from the Developer Applications of your app on GitHub.
21+
2. Set the `Client ID` and `Client Secret` to enviromental variables:
22+
23+
```bash
24+
export OAUTH_GITHUB_KEY=YOUR_CLIENT_ID
25+
export OAUTH_GITHUB_SECRET=YOUR_CLIENT_SECRET
26+
```
27+
28+
## Run server
29+
30+
```bash
31+
python manage.py runserver
32+
```
33+
34+
Go to login page:
35+
36+
![image](https://user-images.githubusercontent.com/6737785/51812454-e7edd980-22f4-11e9-80c6-2f18fbc49108.png)

‎docs/faq.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
## I can't install doccano.
2+
3+
Following list is ordered by from easy to hard. If you are not familiar with Python development, please consider easy setup.
4+
5+
1. [One click deployment to Cloud Service.](https://github.com/chakki-works/doccano#deployment)
6+
* Only you have to do is create an account. Especially [Heroku](https://www.heroku.com/home) does not require your credit card (if free plan).
7+
* [![Deploy to Azure](https://azuredeploy.net/deploybutton.svg)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fchakki-works%2Fdoccano%2Fmaster%2Fazuredeploy.json)
8+
* [![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy)
9+
* [![AWS CloudFormation Launch Stack SVG Button](https://cdn.rawgit.com/buildkite/cloudformation-launch-stack-button-svg/master/launch-stack.svg)](https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/create/review?templateURL=https://s3-external-1.amazonaws.com/cf-templates-10vry9l3mp71r-us-east-1/20190732wl-new.templatexloywxxyimi&stackName=doccano)
10+
* > Notice: (1) EC2 KeyPair cannot be created automatically, so make sure you have an existing EC2 KeyPair in one region. Or [create one yourself](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#having-ec2-create-your-key-pair). (2) If you want to access doccano via HTTPS in AWS, here is an [instruction](https://github.com/chakki-works/doccano/wiki/HTTPS-setting-for-doccano-in-AWS).
11+
2. [Use Docker](https://docs.docker.com/install/)
12+
* Docker doesn't bother you by the OS, Python version, etc problems. Because an environment for application is packed as a container.
13+
* Get doccano's image: `docker pull chakkiworks/doccano`
14+
* Create & Run doccano container: `docker run -d --name doccano -p 8000:80 chakkiworks/doccano`
15+
* Create a user: `docker exec doccano tools/create-admin.sh "admin" "[email protected]" "password"`
16+
* Stop doccano container: `docker stop doccano`
17+
* Re-Launch doccano container: `docker start doccano`
18+
3. Install from source
19+
* **I want to remember you that this is the hardest setup way. You have to install Python/Node.js and type many commands.**
20+
* [Install Python](https://www.python.org/downloads/)
21+
* [Install Node.js](https://nodejs.org/en/download/)
22+
* Get the source code of doccano: `git clone https://github.com/chakki-works/doccano.git`
23+
* Move to doccano directory: `cd doccano`
24+
* Create environment for doccano: `virtualenv venv`
25+
* Activate environment: `source venv/bin/activate`
26+
* Install required packages: `pip install -r requirements.txt`
27+
* Move server directory: `cd app/server`
28+
* Build frontend library: `npm install`
29+
* Build frontend source code: `npm run build`
30+
* Back to server directory: `cd ../`
31+
* Initialize doccano: `python manage.py migrate`
32+
* Create user: `python manage.py createsuperuser`
33+
* Run doccano: `python manage.py runserver`
34+
* Stop doccano: Ctrl+C
35+
* Re-Launch doccano: `python manage.py runserver` (Confirm you are at `app/server` directory and environment is active).
36+
37+
## I can't upload my data.
38+
39+
Please check the following list.
40+
41+
- File encoding: `UTF-8` is appropriate.
42+
- Filename: alphabetic file name is suitable.
43+
- File format selection: File format radio button should be selected properly.
44+
- When you are using JSON/JSONL: Confirm JSON data is valid.
45+
- You can use [JSONLint](https://jsonlint.com/) or some other tool (when JSONL, pick one data and check it).
46+
- When you are using CSV: Confirm CSV data is valid.
47+
- You can use Excel or some tools that have import CSV feature.
48+
- Lack of line: Data file should not contain blank line.
49+
- Lack of field: Data file should not contain blank field.
50+
51+
**You don't need your real & all data to validate file format. The picked data & masked data is suitable if your data is large or secret.**
52+
53+
## I want to add annotators.
54+
55+
* You can create other annotators by [Django Admin site](https://djangobook.com/django-admin-site/).

‎docs/getting-started.md

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Getting started
2+
3+
## Quick install guide
4+
5+
First of all, you have to clone the repository:
6+
7+
```bash
8+
git clone https://github.com/chakki-works/doccano.git
9+
cd doccano
10+
```
11+
12+
To install doccano, there are three options:
13+
14+
### Option1: Pull the production Docker image
15+
16+
```bash
17+
docker pull chakkiworks/doccano
18+
```
19+
20+
### Option2: Pull the development Docker-Compose images
21+
22+
```bash
23+
docker-compose pull
24+
```
25+
26+
### Option3: Setup Python environment
27+
28+
First we need to install the dependencies. Run the following commands:
29+
30+
```bash
31+
pip install -r requirements.txt
32+
cd app
33+
```
34+
35+
Next we need to start the webpack server so that the frontend gets compiled continuously.
36+
Run the following commands in a new shell:
37+
38+
```bash
39+
cd server/static
40+
npm install
41+
npm run build
42+
# npm start # for developers
43+
cd ..
44+
```
45+
46+
## Usage
47+
48+
Let’s start the development server and explore it.
49+
50+
Depending on your installation method, there are two options:
51+
52+
### Option1: Running the Docker image as a Container
53+
54+
First, run a Docker container:
55+
56+
```bash
57+
docker run -d --name doccano -p 8000:80 chakkiworks/doccano
58+
```
59+
60+
Then, execute `create-admin.sh` script for creating a superuser.
61+
62+
```bash
63+
docker exec doccano tools/create-admin.sh "admin" "[email protected]" "password"
64+
```
65+
66+
### Option2: Running the development Docker-Compose stack
67+
68+
We can use docker-compose to set up the webpack server, django server, database, etc. all in one command:
69+
70+
```bash
71+
docker-compose up
72+
```
73+
74+
Now, open a Web browser and go to <http://127.0.0.1:8000/login/>. You should see the login screen:
75+
76+
![Login form](./login_form.png)
77+
78+
### Option3: Running Django development server
79+
80+
Before running, we need to make migration. Run the following command:
81+
82+
```bash
83+
python manage.py migrate
84+
```
85+
86+
Next we need to create a user who can login to the admin site. Run the following command:
87+
88+
```bash
89+
python manage.py create_admin --noinput --username "admin" --email "[email protected]" --password "password"
90+
```
91+
92+
Developers can also validate that the project works as expected by running the tests:
93+
94+
```bash
95+
python manage.py test server.tests
96+
```
97+
98+
Finally, to start the server, run the following command:
99+
100+
```bash
101+
python manage.py runserver
102+
```

‎docs/index.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Welcome to doccano
2+
3+
## Text Annotation for Human
4+
5+
doccano is an open source text annotation tool for human. It provides annotation features for text classification, sequence labeling and sequence to sequence. So, you can create labeled data for sentiment analysis, named entity recognition, text summarization and so on. Just create project, upload data and start annotation. You can build dataset in hours.
6+
7+
8+
## Demo
9+
10+
You can enjoy [annotation demo](http://doccano.herokuapp.com).
11+
12+
### [Named entity recognition](https://doccano.herokuapp.com/demo/named-entity-recognition/)
13+
14+
First demo is one of the sequence labeling tasks, named-entity recognition. You just select text spans and annotate it. Since doccano supports shortcut key, so you can quickly annotate text spans.
15+
16+
![Named Entity Recognition](./named_entity_annotation.gif)
17+
18+
### [Sentiment analysis](https://doccano.herokuapp.com/demo/text-classification/)
19+
20+
Second demo is one of the text classification tasks, topic classification. Since there may be more than one category, you can annotate multi-labels.
21+
22+
![Text Classification](./text_classification.gif)
23+
24+
### [Machine translation](https://doccano.herokuapp.com/demo/translation/)
25+
26+
Final demo is one of the sequence to sequence tasks, machine translation. Since there may be more than one responses in sequence to sequence tasks, you can create multi responses.
27+
28+
![Machine Translation](./translation.gif)
29+
30+
## Quick Deployment
31+
32+
### Azure
33+
34+
Doccano can be deployed to Azure ([Web App for Containers](https://azure.microsoft.com/en-us/services/app-service/containers/) +
35+
[PostgreSQL database](https://azure.microsoft.com/en-us/services/postgresql/)) by clicking on the button below:
36+
37+
[![Deploy to Azure](https://azuredeploy.net/deploybutton.svg)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fchakki-works%2Fdoccano%2Fmaster%2Fazuredeploy.json)
38+
39+
### Heroku
40+
41+
Doccano can be deployed to [Heroku](https://www.heroku.com/) by clicking on the button below:
42+
43+
[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy)
44+
45+
Of course, you can deploy doccano by using [heroku-cli](https://devcenter.heroku.com/articles/heroku-cli).
46+
47+
```bash
48+
heroku create
49+
heroku stack:set container
50+
git push heroku master
51+
```
52+
53+
### AWS
54+
55+
Doccano can be deployed to AWS ([Cloudformation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)) by clicking on the button below:
56+
57+
[![AWS CloudFormation Launch Stack SVG Button](https://cdn.rawgit.com/buildkite/cloudformation-launch-stack-button-svg/master/launch-stack.svg)](https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/create/review?templateURL=https://s3-external-1.amazonaws.com/cf-templates-10vry9l3mp71r-us-east-1/20190732wl-new.templatexloywxxyimi&stackName=doccano)
58+
59+
> Notice: (1) EC2 KeyPair cannot be created automatically, so make sure you have an existing EC2 KeyPair in one region. Or [create one yourself](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#having-ec2-create-your-key-pair). (2) If you want to access doccano via HTTPS in AWS, here is an [instruction](https://github.com/chakki-works/doccano/wiki/HTTPS-setting-for-doccano-in-AWS).

0 commit comments

Comments
 (0)