From ad31a67d8fc95692b4a4dbd20dd0915b8811bda4 Mon Sep 17 00:00:00 2001 From: Martin Zimmermann Date: Wed, 19 Mar 2014 14:00:16 +0100 Subject: [PATCH 1/7] get doc version via installed distribution --- docs/conf.py | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 1699786..b114fe3 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. From b19084b3e2b9f6c34a578b8bd27c84012f0b55af Mon Sep 17 00:00:00 2001 From: Martin Zimmermann Date: Wed, 19 Mar 2014 14:00:49 +0100 Subject: [PATCH 2/7] add manpage stuff --- MANIFEST.in | 3 +++ docs/conf.py | 6 ++++-- docs/docs/man/index.rst | 38 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 45 insertions(+), 2 deletions(-) create mode 100644 docs/docs/man/index.rst 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/docs/conf.py b/docs/conf.py index b114fe3..1c2581e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -232,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/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 + From 5df4b40a1fe0d222f5565e50085fa710706ab9fd Mon Sep 17 00:00:00 2001 From: Martin Zimmermann Date: Wed, 19 Mar 2014 15:58:40 +0100 Subject: [PATCH 3/7] rewrite Makefile --- Makefile | 40 +++++++++++++++++++++++++++++----------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/Makefile b/Makefile index f1d2d4d..1de26ff 100644 --- a/Makefile +++ b/Makefile @@ -1,22 +1,40 @@ -all: css js +ISSO_SRC := $(shell find isso/js/app -type f) $(shell ls isso/js/*.js | grep -vE "(min|dev)") +ISSO_DST := isso/js/embed.min.js isso/js/embed.dev.js isso/js/count.min.js isso/js/count.dev.js + +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/js/%.min.js: $(ISSO_SRC) + r.js -o isso/js/build.$*.js out=$@ + +isso/js/%.dev.js: $(ISSO_SRC) + r.js -o isso/js/build.$*.js optimize="none" 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" +js: $(ISSO_DST) -site: - cd docs/ && sphinx-build -E -b dirhtml -a . _build - scss docs/_static/css/site.scss docs/_build/_static/css/site.css +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_DST) + +.PHONY: clean site man init js + From ac41731c6a31e4ba33df14c01b76430c97aab712 Mon Sep 17 00:00:00 2001 From: Martin Zimmermann Date: Wed, 19 Mar 2014 16:10:15 +0100 Subject: [PATCH 4/7] update changelog to reflect latest changes --- CHANGES.rst | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) 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/ From 2c2c911ba4d7f5c5a595760300f2e15497b7d9a6 Mon Sep 17 00:00:00 2001 From: Martin Zimmermann Date: Wed, 19 Mar 2014 16:19:23 +0100 Subject: [PATCH 5/7] Isso requires SQLite 3.3.8 or later --- docs/docs/install.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/docs/install.rst b/docs/docs/install.rst index 5e32bce..7efe8a7 100644 --- a/docs/docs/install.rst +++ b/docs/docs/install.rst @@ -4,6 +4,7 @@ Installation 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 `_: From e75fa4b7e1d66dfa1eba929979c89a24eb6a02bb Mon Sep 17 00:00:00 2001 From: Martin Zimmermann Date: Thu, 20 Mar 2014 11:19:37 +0100 Subject: [PATCH 6/7] add target to generate Isso's CSS --- Makefile | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/Makefile b/Makefile index 1de26ff..f3fb7c5 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,9 @@ -ISSO_SRC := $(shell find isso/js/app -type f) $(shell ls isso/js/*.js | grep -vE "(min|dev)") -ISSO_DST := isso/js/embed.min.js isso/js/embed.dev.js isso/js/count.min.js isso/js/count.dev.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 @@ -12,13 +16,17 @@ all: man js site init: (cd isso/js; bower install almond requirejs requirejs-text) -isso/js/%.min.js: $(ISSO_SRC) +${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=$@ -isso/js/%.dev.js: $(ISSO_SRC) +isso/js/%.dev.js: $(ISSO_JS_SRC) $(ISSO_CSS_DST) r.js -o isso/js/build.$*.js optimize="none" out=$@ -js: $(ISSO_DST) +js: $(ISSO_JS_DST) +css: $(ISSO_CSS_DST) man: $(RST) sphinx-build -b man docs/ man/ @@ -34,7 +42,7 @@ coverage: --cover-package=isso --cover-html isso/ specs/ clean: - rm -f $(MAN) $(CSS) $(ISSO_DST) + rm -f $(MAN) $(CSS) $(ISSO_JS_DST) $(ISSO_CSS_DST) -.PHONY: clean site man init js +.PHONY: clean site man init js css From de50c683bc80d6e342dc66d92337aaac86160d46 Mon Sep 17 00:00:00 2001 From: Martin Zimmermann Date: Thu, 20 Mar 2014 11:38:47 +0100 Subject: [PATCH 7/7] extend installation docs * add interludium for users new to Python * include guides for prebuilt packages and building from source (obsoletes DEVELOPMENT.md). --- docs/DEVELOPMENT.md | 59 --------------- docs/docs/install.rst | 168 +++++++++++++++++++++++++++++++++++++++++- 2 files changed, 166 insertions(+), 61 deletions(-) delete mode 100644 docs/DEVELOPMENT.md 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/docs/install.rst b/docs/docs/install.rst index 7efe8a7..b3cdb99 100644 --- a/docs/docs/install.rst +++ b/docs/docs/install.rst @@ -1,5 +1,74 @@ 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: @@ -13,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):