From 4261623d1a720138de4a15a139993dabf7540e61 Mon Sep 17 00:00:00 2001
From: Diffido <diffido@localhost>
Date: Fri, 26 Jan 2018 15:08:42 +0100
Subject: [PATCH] add documentation

---
 README.md           | 84 +++++++++++++++++++++++++++++++++++++++++++--
 conf/diffido.conf   |  2 +-
 docs/DEVELOPMENT.md | 34 ++++++++++++++++++
 3 files changed, 117 insertions(+), 3 deletions(-)
 create mode 100644 docs/DEVELOPMENT.md

diff --git a/README.md b/README.md
index a7ec84d..3f77a03 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,83 @@
-# diffido
+# Diffido
+
+Spot the difference on the web.
+
+Tired of clicking F5 waiting for a change on a web page? Define a list of pages to watch, and receive an email when something has changed.
+
+
+# Demo
+
+See [http://ismito.it:3210/](http://ismito.it:3210/) (you can only add \*.wikipedia.org pages, there)
+
+
+## Install, run, develop and debug
+
+## Docker
+
+Just run:
+
+    ./run-docker.sh
+
+
+## Old-fashioned installation
+
+To install it:
+``` bash
+wget https://bootstrap.pypa.io/get-pip.py
+sudo python3 get-pip.py
+# if you want to install these modules for an unprivileged user, add --user and remove "sudo";
+# if you want to upgrade the versions already present in the system, also add --upgrade
+sudo pip3 install apscheduler
+sudo pip3 install requests
+sudo pip3 install sqlalchemy
+sudo pip3 install tornado
+git clone https://github.com/alberanid/diffido
+cd diffido
+./diffido.py --debug
+```
+
+Now you can **point your browser to [http://localhost:3210/](http://localhost:3210/)**
+
+You can also **run the server in https**, putting in the *ssl* directory two files named *diffido_key.pem* and *diffido_cert.pem*
+
+
+# Settings
+
+You can edit the *conf/diffido.conf* file (Python syntax) to change the global settings; you almost surely have to configure the SMTP settings, at least.
+
+Each schedule has its own web page GUI; the settings should be pretty self-explanatory, except:
+
+- **XPath seelctor**: define which portion of a web page to consider
+- **minimum change**: float between 0.0 and 1.0, which represent the minimum amount of the page (in percentage of number of lines) that has to be changed to send a notification; if left empty, any change will be notified
+- **crontab**: a complete crontab definition, to specify the period of the check
+
+
+# Development
+
+See the *docs/DEVELOPMENT.md* file for more information about how to contribute.
+
+
+## Technological stack
+
+- [VueJS 2](https://vuejs.org/) for the webApp
+- [Vue Material](https://vuematerial.github.io/) for the UI components
+- [Tornado web](http://www.tornadoweb.org/) as web server
+- [APScheduler](https://github.com/agronholm/apscheduler) to run the scheduled jobs
+- [Python 3](https://www.python.org/)
+- [Git](https://git-scm.com/) to store the data
+
+
+# License and copyright
+
+Copyright 2018 Davide Alberani <da@erlug.linux.it>
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
 
-Spot the difference on the web
diff --git a/conf/diffido.conf b/conf/diffido.conf
index 1930b2f..7d5d23f 100644
--- a/conf/diffido.conf
+++ b/conf/diffido.conf
@@ -1,4 +1,4 @@
-debug=True
+debug=False
 admin_email='diffido@localhost'
 smtp_host='localhost'
 #smtp_port=0
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
new file mode 100644
index 0000000..93cd149
--- /dev/null
+++ b/docs/DEVELOPMENT.md
@@ -0,0 +1,34 @@
+# Diffido development
+
+## API
+
+- /api/schedules GET - the list of all schedules
+- /api/schedules POST - add a new schedule
+- /api/schedules/reset POST - reset all schedules using the JSON configuration
+- /api/schedules/:id GET - get a single schedule
+- /api/schedules/:id PUT - update a schedule
+- /api/schedules/:id DELETE - delete a schedule
+- /api/schedules/:id/run POST - immediately run a schedule
+- /api/schedules/:id/history GET - get the history of a schedule
+- /api/schedules/:id/diff/:commit_id/:old_commit_id GET - get the diff from two commits of a schedule
+
+
+## Data layout
+
+Information are stored in:
+
+- **conf/diffido.conf**: global options (Python syntax), can also be passed on the command line
+- **conf/schedules.json**: the JSON file used to store the schedules settings
+- **conf/jobs.db**: SQLite database used by APScheduler
+- **storage/**: git repositories, one for each schedule
+
+
+Coding style and conventions
+----------------------------
+
+It's enough to be consistent within the document you're editing.
+
+I suggest four spaces instead of tabs for all the code: Python (**mandatory**), JavaScript, HTML and CSS.
+
+Python code documented following the [Sphinx](http://sphinx-doc.org/) syntax.
+