diff --git a/CHANGES.rst b/CHANGES.rst
index ef69b83..e2ab157 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -4,7 +4,30 @@ Changelog for Isso
0.8 (unreleased)
----------------
-- Nothing changed yet.
+- fix undefined timestamp when client time differs for more than 1 second.
+ The human-readable "time ago" deltas have been refined to match `Moment.js`_
+ behavior.
+
+- avatar colors and background can now be customized:
+
+ * ``data-isso-avatar-bg="#f0f0f0"`` sets the background color
+ * ``data-isso-avatar-fg="#9abf88 #5698c4 #e279a3 #9163b6 ..."`` sets possible
+ avatar colors (up to 8 colors are possible).
+
+- new [markup] section to customize Misaka's Markdown generation (strikethrough,
+ superscript and autolink enabled by default). Furthermore, you can now allow
+ certain HTML elemenets and attributes in the generated output, e.g. to enable
+ images, set
+
+ [markup]
+ allowed-elements = img
+ allowed-attributes = src
+
+ Check docs/configuration/server.rst for more details.
+
+- replace requirejs-domready with a (self-made) HTML5 idiom, #51
+
+.. _Moment.js: http://momentjs.com/docs/#/displaying/fromnow/
0.7 (2014-01-29)
@@ -32,6 +55,7 @@ Changelog for Isso
- the (by default random) session-key is now shown on application startup
to make different keys per startup more visible
+
- use `threading.lock` by default for systems without semaphore support
.. _Transifex: https://www.transifex.com/projects/p/isso/
diff --git a/MANIFEST.in b/MANIFEST.in
index e0debfb..d79f6fe 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,3 +1,6 @@
+include man/man1/isso.1
+include man/man5/isso.conf.5
+
include isso/js/embed.min.js
include isso/js/embed.dev.js
include isso/js/count.min.js
diff --git a/Makefile b/Makefile
index f1d2d4d..f3fb7c5 100644
--- a/Makefile
+++ b/Makefile
@@ -1,22 +1,48 @@
-all: css js
+ISSO_JS_SRC := $(shell find isso/js/app -type f) $(shell ls isso/js/*.js | grep -vE "(min|dev)")
+ISSO_JS_DST := isso/js/embed.min.js isso/js/embed.dev.js isso/js/count.min.js isso/js/count.dev.js
+
+ISSO_CSS_DST := isso/css/isso.css
+ISSO_CSS_SRC := isso/css/isso.scss
+ISSO_CSS_SRC_DEPS := $(shell find isso/css -type f | grep .scss)
+
+RST := $(shell find docs/ -type f -name '*.rst')
+MAN := man/man1/isso.1 man/man5/isso.conf.5
+
+WWW := docs/index.html docs/isso.example.cfg $(wildcard docs/_static/*)
+CSS := docs/_static/css/site.css
+
+all: man js site
init:
(cd isso/js; bower install almond requirejs requirejs-text)
-css:
- scss isso/css/isso.scss isso/css/isso.css
+${ISSO_CSS_DST}: $(ISSO_CSS_SRC_DEPS)
+ scss --no-cache $(ISSO_CSS_SRC) $@
+
+isso/js/%.min.js: $(ISSO_JS_SRC) $(ISSO_CSS_DST)
+ r.js -o isso/js/build.$*.js out=$@
-js:
- r.js -o isso/js/build.embed.js
- r.js -o isso/js/build.embed.js optimize="none" out="isso/js/embed.dev.js"
- r.js -o isso/js/build.count.js
- r.js -o isso/js/build.count.js optimize="none" out="isso/js/count.dev.js"
+isso/js/%.dev.js: $(ISSO_JS_SRC) $(ISSO_CSS_DST)
+ r.js -o isso/js/build.$*.js optimize="none" out=$@
-site:
- cd docs/ && sphinx-build -E -b dirhtml -a . _build
- scss docs/_static/css/site.scss docs/_build/_static/css/site.css
+js: $(ISSO_JS_DST)
+css: $(ISSO_CSS_DST)
+
+man: $(RST)
+ sphinx-build -b man docs/ man/
+
+${CSS}: docs/_static/css/site.scss
+ scss --no-cache $< $@
+
+site: $(RST) $(WWW) $(CSS)
+ cd docs && sphinx-build -b dirhtml . _build/html
coverage:
nosetests --with-doctest --with-doctest-ignore-unicode --with-coverage \
--cover-package=isso --cover-html isso/ specs/
+clean:
+ rm -f $(MAN) $(CSS) $(ISSO_JS_DST) $(ISSO_CSS_DST)
+
+.PHONY: clean site man init js css
+
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
deleted file mode 100644
index c5e38c3..0000000
--- a/docs/DEVELOPMENT.md
+++ /dev/null
@@ -1,59 +0,0 @@
-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:
-
- ~> make init
- ~> # or cd isso/js && bower install almond requirejs requirejs-text
-
-
-Integration
------------
-
-```html
-
-
-```
-
-
-Optimization
-------------
-
- ~> npm install -g requirejs uglifyjs
- ~> make js
- ~> # or r.js -o /isso/js/build.embed.js
diff --git a/docs/conf.py b/docs/conf.py
index 1699786..1c2581e 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -12,6 +12,9 @@
# All configuration values have a default; values that are commented out
# serve to show the default.
+import pkg_resources
+dist = pkg_resources.get_distribution("isso")
+
import sys
import os
@@ -54,11 +57,14 @@ copyright = u'2013, Martin Zimmermann'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
+
+from distutils.version import LooseVersion
+
#
-# The short X.Y version.
-version = '0.5'
# The full version, including alpha/beta/rc tags.
-release = '0.5.1'
+release = dist.version
+# The short X.Y version.
+version = "{0}.{1}".format(*LooseVersion(dist.version).version)
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@@ -226,8 +232,10 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- ('index', 'isso', u'Isso Documentation',
- [u'Martin Zimmermann'], 1)
+ ('docs/man/index', 'man1/isso', u'a Disqus alternative',
+ [u'Martin Zimmermann'], 1),
+ ('docs/configuration/server', 'man5/isso.conf', u'server configuration',
+ [u'Martin Zimmermann'], 5)
]
# If true, show URL addresses after external links.
diff --git a/docs/docs/install.rst b/docs/docs/install.rst
index 5e32bce..b3cdb99 100644
--- a/docs/docs/install.rst
+++ b/docs/docs/install.rst
@@ -1,9 +1,79 @@
Installation
-------------
+============
+
+Isso is a web application written in Python. If pip and virtualenv mean
+anything to you, continue with :ref:`install-from-pypi`. If you are running
+Debian/Ubuntu or Gentoo, you can use :ref:`prebuilt-package`. If not, read the
+next section carefully.
+
+.. contents::
+ :local:
+ :depth: 1
+
+Interludium: Python is not PHP
+------------------------------
+
+If you think hosting a web application written in Python is as easy as one
+written in PHP, you are wrong. Unlike for PHP, many Linux distribution use
+Python for internal tools. Your package manager already ships several python
+libraries, but most likely not all required by Isso (or in an up-to-date
+version – looking at you, Debian!).
+
+That's why most Python developers use the `Python Package Index`_ to get their
+packages. But the most important rule: never install *anything* from PyPi as
+root. Not because of malicious software, but because you *will* break your
+system.
+``easy_install`` is one tool to mess up your system. Another package manager is
+``pip``. If you ever searched for an issue with Python/pip and Stackoverflow is
+suggesting your ``easy_install pip`` or ``pip install --upgrade pip`` (as root
+of course!), you are doing it wrong. `Why you should not use Python's
+easy_install carelessly on Debian`_ is worth the read.
+
+Fortunately, Python has a way to install packages (both as root and as user)
+without interfering with your globally installed packages: `virtualenv`. Use
+this *always* if you are installing software unavailable in your favourite
+package manager.
+
+.. code-block:: sh
+
+ # for Debian/Ubuntu
+ ~> sudo apt-get install python-setuptools python-virtualenv
+
+ # Fedora/Red Hat
+ ~> sudo yum install python-setuptools python-virtualenv
+
+The next steps should be done as regular user, not as root (although possible
+but not recommended):
+
+.. code-block:: sh
+
+ ~> virtualenv /home/user/python/isso
+ ~> source /home/user/python/isso/activate
+
+After calling `source`, you can now install packages from PyPi locally into this
+virtual environment. If you don't like Isso anymore, you just `rm -rf` the
+folder. Inside this virtual environment, you may also execute the example
+commands from above to upgrade your Python Package Manager (although it barely
+makes sense), it is completely independent from your global system.
+
+With a virtualenv ready, you may now continue to :ref:`install-from-pypi`!
+Note, that if you are using a slightly more advanced shared-hoster or virtual
+machines, you may not need virtual environments.
+
+
+.. _Python Package Index: https://pypi.python.org/pypi
+.. _Why you should not use Python's easy_install carelessly on Debian:
+ https://workaround.org/easy-install-debian
+
+.. _install-from-pypi:
+
+Install from PyPi
+-----------------
Requirements:
- Python 2.6, 2.7 or 3.3 (+ devel headers)
+- SQLite 3.3.8 or later
- a working C compiler
Install Isso with `pip `_:
@@ -12,12 +82,107 @@ Install Isso with `pip `_:
~> pip install isso
-`Dont't have pip `_?
+`Don't have pip? `_
.. code-block:: sh
~> easy_install isso # cross your fingers
+If you are using a virtualenv, you don't need to activate the environment
+every time you want to start Isso. You can symlink the executable to a location
+in your PATH:
+
+.. code-block:: sh
+
+ ~> ln -s /path/to/isso-venv/bin/isso /usr/local/bin/isso
+
+To upgrade Isso, activate your virtual environment once again, and run
+
+.. code-block:: sh
+
+ ~> pip install --upgrade isso
+
+.. _prebuilt-package:
+
+Prebuilt Packages
+-----------------
+
+* Debian: https://packages.crapouillou.net/ – built from PyPi. Includes
+ startup scripts and vhost configurations for Lighttpd, Apache and Nginx
+ [`source `__].
+
+ `#729218 `_ is a
+ ITP for Debian. To be officially packages by Debian, `#51
+ `_ needs to be done (contributions
+ are welcome).
+
+* Gentoo: http://eroen.eu/cgit/cgit.cgi/eroen-overlay/tree/www-apps/isso?h=isso
+ – not yet available in Portage, but you can use the ebuild to build Isso.
+
+Install from Source
+-------------------
+
+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:
+
+- Python 2.6, 2.7 or 3.3 (+ devel headers)
+- SQLite 3.3.8 or later
+- a working C compiler
+- Ruby 1.8 or higher
+- SASS 3.0 or higher
+- Node.js, `NPM `__ and `Bower `__
+
+Get a fresh copy of Isso:
+
+.. code-block:: sh
+
+ ~> git clone https://github.com/posativ/isso.git
+ ~> cd isso/
+
+To create a virtual environment (recommended), run:
+
+.. code-block:: sh
+
+ ~> pip install virtualenv
+ ~> virtualenv .
+ ~> source ./bin/activate
+
+Install Isso and its dependencies:
+
+.. code-block:: sh
+
+ ~> python setup.py develop # or `install`
+ ~> isso run
+
+Compilation from SCSS to CSS:
+
+.. code-block:: sh
+
+ ~> make css
+
+Install JavaScript modules:
+
+.. code-block:: sh
+
+ ~> make init
+
+Integration without previous optimzation:
+
+.. code-block:: html
+
+
+
+
+Optimization
+
+.. code-block:: sh
+
+ ~> npm install -g requirejs uglifyjs
+ ~> make js
+
+Init scripts
+------------
+
Init scripts to run Isso as a service (check your distribution's documentation
for your init-system; e.g. Debian uses SysVinit, Fedora uses SystemD):
diff --git a/docs/docs/man/index.rst b/docs/docs/man/index.rst
new file mode 100644
index 0000000..072b4c4
--- /dev/null
+++ b/docs/docs/man/index.rst
@@ -0,0 +1,38 @@
+Isso
+====
+
+What's Isso?
+------------
+
+Isso is a lightweight commenting server similar to Disqus. It allows anonymous
+comments, maintains identity and is simple to administrate. It uses JavaScript
+and cross-origin ressource sharing for easy integration into static websites.
+
+No, I meant "Isso"
+------------------
+
+Isso is an informal, german abbreviation for "Ich schrei sonst!", which can
+roughly be translated to "I'm yelling otherwise". It usually ends the
+discussion without any further arguments.
+
+In germany, Isso `is also pokémon N° 360`__.
+
+.. __: http://bulbapedia.bulbagarden.net/wiki/Wynaut_(Pok%C3%A9mon)
+
+What's wrong with Disqus?
+-------------------------
+
+No anonymous comments (IP address, email and name recorded), hosted in the USA,
+third-party. Just like IntenseDebate, livefrye etc. When you embed Disqus, they
+can do anything with your readers (and probably mine Bitcoins, see the loading
+times).
+
+Setup
+-----
+
+.. toctree::
+ :maxdepth: 1
+
+ ../quickstart
+ ../troubleshooting
+