arno
/
isso
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

update README and add CONTRIBUTING page

Browse Source
legacy/0.2
Martin Zimmermann 11 years ago
parent 381603ebd7
commit f6e190d341
2 changed files with 129 additions and 59 deletions
Show Stats Download Patch File Download Diff File

90
CONTRIBUTING.md
Unescape View File

@ -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 `<ipAddress>`
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
<link rel="stylesheet" href="/isso/static/isso.css" />
<script src="/isso/js/config.js"></script>
<script data-main="/isso/js/embed" src="/isso/js/components/requirejs/require.js"></script>
```
Optimization
------------
~> npm install -g requirejs uglifyjs
~> cd isso/js
~> r.js -o build.embed.js
~> r.js -o build.count.js

98
README.md
Unescape View File

@ -4,7 +4,7 @@ Isso – Ich schrei sonst
You love static blog generators (especially [Acrylamid][1] *cough*) and the You love static blog generators (especially [Acrylamid][1] *cough*) and the
only option to interact with the community is [Disqus][2]. There's nothing 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 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. Isso comes into play.
[1]: https://github.com/posativ/acrylamid [1]: https://github.com/posativ/acrylamid
@ -38,41 +38,15 @@ Roadmap
Installation 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 - Python 2.6, 2.7 or 3.3
- [NPM](https://npmjs.org/) and [Bower](http://bower.io/) - 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 ~> pip install http://posativ.org/~tmp/isso-latest.tar.gz
~> 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
Before you start, you may want to import comments from Before you start, you may want to import comments from
[Disqus.com](https://disqus.com/): [Disqus.com](https://disqus.com/):
@ -94,7 +68,7 @@ setup has its own benefits.
### Isso on a Sub URI ### 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 ```nginx
server { server {
@ -111,24 +85,42 @@ server {
} }
``` ```
The Isso API endpoint is now `example.tld/isso`, check by `curl`ing the client ```html
JS located at `http://example.tld/isso/js/embed.js`. <link rel="stylesheet" href="http://example.tld/isso/css/isso.css" />
<script src="http://example.tld/isso/js/embed.min.js"></script>
```
### Isso on a Dedicated Domain ### 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 ```html
<link rel="stylesheet" href="http://example.tld/isso/static/isso.css" /> <link rel="stylesheet" href="http://example.tld:8080/css/isso.css" />
<script src="http://example.tld/isso/js/embed.min.js"></script> <script src="http://example.tld:8080/js/embed.min.js"></script>
``` ```
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 `<div id="isso-thread"></div>` below your post and To enable comments, add a `<div id="isso-thread"></div>` below your post and
let the magic happen :-) 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 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. *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
<link rel="stylesheet" href="/isso/static/isso.css" />
<script src="/isso/js/config.js"></script>
<script data-main="/isso/js/embed" src="/isso/js/components/requirejs/require.js"></script>
```
Other Documents
---------------
API - [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)
See [docs/API.md](https://github.com/posativ/isso/blob/master/docs/API.md).
Alternatives Alternatives
@ -165,6 +148,3 @@ Alternatives
- [Juvia](https://github.com/phusion/juvia) – Ruby on Rails - [Juvia](https://github.com/phusion/juvia) – Ruby on Rails
- [Tildehash.com](http://www.tildehash.com/?article=why-im-reinventing-disqus) – PHP - [Tildehash.com](http://www.tildehash.com/?article=why-im-reinventing-disqus) – PHP
- [SO: Unobtrusive, self-hosted comments](http://stackoverflow.com/q/2053217) - [SO: Unobtrusive, self-hosted comments](http://stackoverflow.com/q/2053217)
[r.js]: http://require.js/

Write Preview
Loading…
Cancel
Save