From f6e190d341a371e3bcb3265489abbc4e51b4690c Mon Sep 17 00:00:00 2001 From: Martin Zimmermann Date: Sat, 19 Oct 2013 14:24:36 +0200 Subject: [PATCH] update README and add CONTRIBUTING page --- CONTRIBUTING.md | 90 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 98 ++++++++++++++++++++----------------------------- 2 files changed, 129 insertions(+), 59 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1370921 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,90 @@ +Contributing +============ + +I appreciate any help and love pull requests. Here are some things +you need to respect: + +* no hard-wired external services +* no support for ancient browsers (e.g. IE6-9) + +Reporting Issues +---------------- + +### Disqus import fails + +If `isso import /path/to/disqus.xml` fails, please do *NOT* attach the raw +dump file to GH:Issues. Please anonymize all IP addresses inside the `` +tag first, as second step, replace all email addresses with a generic one ( +email tag). + +### embed.min.js-related issues + +In case of a JavaScript traceback, please setup Isso in development mode +described below. Otherwise it is very hard to "guess" the reason. + +### isso-related issues + +Copy and paste traceback into a ticket and provide some details of your usage. + + +Development +----------- + +If you want to hack on Isso or track down issues, there's an alternate +way to set up Isso. It requires a lot more dependencies and effort. + +Requirements: + +- Python 2.6, 2.7 or 3.3 +- Ruby 1.8 or higher +- Node.js, [NPM](https://npmjs.org/) and [Bower](http://bower.io/) + +On Debian/Ubuntu install the following packages + + ~> sudo aptitude install python-setuptools python-dev npm ruby + ~> ln -s /usr/bin/nodejs /usr/bin/node + +Get the repository: + + ~> git clone https://github.com/posativ/isso.git + ~> cd isso/ + +Install `virtualenv` and create a new environment for Isso (recommended): + + ~> pip install virtualenv + ~> virtualenv . + ~> source ./bin/activate + +Install Isso dependencies: + + ~> python setup.py develop + ~> isso run + +Compile SCSS to CSS: + + ~> gem install sass + ~> scss --watch isso/css/isso.scss + +Install JS components: + + ~> cd isso/js + ~> bower install almond q requirejs requirejs-domready requirejs-text + + +Integration +----------- + +```html + + + +``` + + +Optimization +------------ + + ~> npm install -g requirejs uglifyjs + ~> cd isso/js + ~> r.js -o build.embed.js + ~> r.js -o build.count.js diff --git a/README.md b/README.md index e0317e3..d03a6d1 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Isso – Ich schrei sonst You love static blog generators (especially [Acrylamid][1] *cough*) and the only option to interact with the community is [Disqus][2]. There's nothing wrong with it, but if you care about the privacy of your audience you are -better off with a comment system that is under your control. This is, were +better off with a comment system that is under your control. This is, where Isso comes into play. [1]: https://github.com/posativ/acrylamid @@ -38,41 +38,15 @@ Roadmap Installation ------------ -Requirements: +Note, there is currently no PyPi release, but I'll upload a snapshot +infrequently. Nevertheless, here are the requirements: -- Python 2.6 or 2.7 -- [NPM](https://npmjs.org/) and [Bower](http://bower.io/) +- Python 2.6, 2.7 or 3.3 +- easy_install or pip -On Debian/Ubuntu install the following packages +Install Isso (and its dependencies) with: - ~> sudo aptitude install python-setuptools python-dev npm - ~> ln -s /usr/bin/nodejs /usr/bin/node - -For now (as long as there is no stable version), you need to manually -build everything: - - ~> git clone https://github.com/posativ/isso.git - ~> cd isso/ - ~> python setup.py develop - -To fetch the requires JS components, run: - - ~> cd isso/js/ - ~> bower install almond q requirejs requirejs-domready requirejs-text - -You can now either use the JS client as-is (using [require.js][r.js], see -below) or compile all JS into a single file: - - ~> cd isso/js - ~> npm install -g requirejs uglifyjs - ~> r.js -o build.embed.js - ~> r.js -o build.count.js - -At last, you need to build the CSS: - - ~> cd ../css - ~> gem install sass - ~> scss isso.scss > isso.css + ~> pip install http://posativ.org/~tmp/isso-latest.tar.gz Before you start, you may want to import comments from [Disqus.com](https://disqus.com/): @@ -94,7 +68,7 @@ setup has its own benefits. ### Isso on a Sub URI -Let's assume you want Isso on `/isso`, use the following nginx snippet +Let's assume you want Isso on `/isso`, use the following nginx snippet: ```nginx server { @@ -111,24 +85,42 @@ server { } ``` -The Isso API endpoint is now `example.tld/isso`, check by `curl`ing the client -JS located at `http://example.tld/isso/js/embed.js`. +```html + + +``` ### Isso on a Dedicated Domain -... +Now, assuming you have your isso instance running on a different URL, such as +`http://example.tld:8080`, but your blog runs on `http://example.tld`: + ~> cat example.cfg + [general] + host = http://example.tld/ + ~> isso -c example.cfg run + * connecting to SMTP server [failed] + * connecting to HTTP server [ok] + * Running on http://localhost:8080/ -Website Integration -------------------- +Make sure, Isso can connect to server that hosts your blog, otherwise you are +not able to post comments. -Add the following two lines into your HTML header: +Integrate Isso with: ```html - - + + ``` +Also, put the plain isso server behind a real web server or [use uWSGI][3]. + +[3]: https://github.com/posativ/isso/blob/master/docs/CONTRIBUTING.md + + +Website Integration +------------------- + To enable comments, add a `
` below your post and let the magic happen :-) @@ -139,23 +131,14 @@ updated with the current comment count. This functionality is already included when you embed `embed.min.js`, do *not* mix `embed.min.js` and `count.min.js` in a single document. -### Embed with require.js -This section is primarily for developers: The client-side JS is modularized -and uses an AMD loader for execution. You can easily hack on the JS files, -when using [require.js][r.js]: - -```html - - - -``` +Other Documents +--------------- -API ---- - -See [docs/API.md](https://github.com/posativ/isso/blob/master/docs/API.md). +- [Configuration](https://github.com/posativ/isso/raw/master/docs/CONFIGURATION.md) +- [API overview](https://github.com/posativ/isso/raw/master/docs/API.md) +- [uWSGI usage](https://github.com/posativ/isso/blob/master/docs/uWSGI.md) Alternatives @@ -165,6 +148,3 @@ Alternatives - [Juvia](https://github.com/phusion/juvia) – Ruby on Rails - [Tildehash.com](http://www.tildehash.com/?article=why-im-reinventing-disqus) – PHP - [SO: Unobtrusive, self-hosted comments](http://stackoverflow.com/q/2053217) - - -[r.js]: http://require.js/