Merge branch 'doc-improvements'

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/

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

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) $@
 
-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/%.min.js: $(ISSO_JS_SRC) $(ISSO_CSS_DST)
+	r.js -o isso/js/build.$*.js out=$@
 
-site:
-	cd docs/ && sphinx-build -E -b dirhtml -a . _build
-	scss docs/_static/css/site.scss docs/_build/_static/css/site.css
+isso/js/%.dev.js: $(ISSO_JS_SRC) $(ISSO_CSS_DST)
+	r.js -o isso/js/build.$*.js optimize="none" out=$@
+
+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
+

docs/DEVELOPMENT.md

@@ -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
-<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
-    ~> make js
-    ~> # or r.js -o /isso/js/build.embed.js

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.

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 <http://www.pip-installer.org/en/latest/>`_:
@@ -12,12 +82,107 @@ Install Isso with `pip <http://www.pip-installer.org/en/latest/>`_:
 
     ~> pip install isso
 
-`Dont't have pip <https://twitter.com/gardaud/status/357638468572151808>`_?
+`Don't have pip? <https://twitter.com/gardaud/status/357638468572151808>`_
 
 .. 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 <https://github.com/jgraichen/debian-isso>`__].
+
+  `#729218 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=729218>`_ is a
+  ITP for Debian. To be officially packages by Debian, `#51
+  <https://github.com/posativ/isso/issues/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 <https://npmjs.org/>`__ and `Bower <http://bower.io/>`__
+
+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
+
+    <script src="/js/config.js"></script>
+    <script data-main="/js/embed" src="/js/components/requirejs/require.js"></script>
+
+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):
 

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
+