add documentation
This commit is contained in:
Diffido
parent
8622c4eb89
commit
4261623d1a
3 changed files with 117 additions and 3 deletions
84
README.md
84
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
|
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
debug=True
|
debug=False
|
||||||
admin_email='diffido@localhost'
|
admin_email='diffido@localhost'
|
||||||
smtp_host='localhost'
|
smtp_host='localhost'
|
||||||
#smtp_port=0
|
#smtp_port=0
|
||||||
|
|
|
||||||
34
docs/DEVELOPMENT.md
Normal file
34
docs/DEVELOPMENT.md
Normal file
|
|
@ -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.
|
||||||
|
|
||||||
Loading…
Reference in a new issue