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'
|
||||
smtp_host='localhost'
|
||||
#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