reword and clean documentation
This commit is contained in:
Martin Zimmermann
parent
d3aa8129c4
commit
cb36107eda
@ -69,6 +69,8 @@ and not a multiple of 2, the color distribution is not even.
|
||||
data-isso-id
|
||||
------------
|
||||
|
||||
Broken – do not use. https://github.com/posativ/isso/issues/27
|
||||
|
||||
Set a custom thread id, defaults to current URI. If you a comment counter, add
|
||||
this attribute to the link tag, too.
|
||||
|
||||
|
||||
@ -1 +0,0 @@
|
||||
../../../share/isso.conf
|
||||
@ -3,8 +3,8 @@ Server Configuration
|
||||
|
||||
The Isso configuration file is an `INI-style`__ textfile. It reads integers,
|
||||
booleans, strings and lists. Here's the default isso configuration:
|
||||
:download:`isso.conf <isso.conf>`. A basic configuration from
|
||||
scratch looks like this:
|
||||
`isso.conf <https://github.com/posativ/isso/blob/master/share/isso.conf>`. A
|
||||
basic configuration from scratch looks like this:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
|
||||
@ -1,9 +1,9 @@
|
||||
Overview
|
||||
========
|
||||
|
||||
Welcome to the Isso's documentation. This documentation will help you get
|
||||
started fast. If you get any problems when using Isso, you can find the answer
|
||||
in troubleshooting or you can ask me on IRC or GitHub.
|
||||
Welcome to Isso's documentation. This documentation will help you get started
|
||||
fast. If you get any problems when using Isso, you can find the answer in
|
||||
troubleshooting guide or you can ask me on IRC or GitHub.
|
||||
|
||||
Documentation overview:
|
||||
|
||||
@ -19,7 +19,7 @@ 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.
|
||||
and cross-origin ressource sharing for easy integration into (static) websites.
|
||||
|
||||
No, I meant "Isso"
|
||||
------------------
|
||||
|
||||
@ -20,8 +20,8 @@ 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
|
||||
dependencies. 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
|
||||
@ -56,10 +56,9 @@ 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.
|
||||
|
||||
With a virtualenv active, you may now continue to :ref:`install-from-pypi`!
|
||||
Of course you may not need a virtualenv when you are running dedicated virtual
|
||||
machines or a shared host (e.g. Uberspace.de).
|
||||
|
||||
.. _Python Package Index: https://pypi.python.org/pypi
|
||||
.. _Why you should not use Python's easy_install carelessly on Debian:
|
||||
@ -72,7 +71,7 @@ Install from PyPi
|
||||
|
||||
Requirements:
|
||||
|
||||
- Python 2.6, 2.7 or 3.3 (+ devel headers)
|
||||
- Python 2.6, 2.7 or 3.3+ (+ devel headers)
|
||||
- SQLite 3.3.8 or later
|
||||
- a working C compiler
|
||||
|
||||
@ -88,15 +87,14 @@ Install Isso with `pip <http://www.pip-installer.org/en/latest/>`_:
|
||||
|
||||
~> 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:
|
||||
For easier execution, 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
|
||||
To upgrade Isso, activate your virtual environment again, and run
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
@ -125,11 +123,12 @@ 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)
|
||||
- Python 2.6, 2.7 or 3.3+ (+ devel headers)
|
||||
- Virtualenv
|
||||
- SQLite 3.3.8 or later
|
||||
- a working C compiler
|
||||
- Ruby 1.8 or higher
|
||||
- SASS 3.0 or higher
|
||||
- a `SCSS <http://sass-lang.com/>`_ compiler
|
||||
- Node.js, `NPM <https://npmjs.org/>`__ and `Bower <http://bower.io/>`__
|
||||
|
||||
Get a fresh copy of Isso:
|
||||
@ -143,7 +142,6 @@ To create a virtual environment (recommended), run:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
~> pip install virtualenv
|
||||
~> virtualenv .
|
||||
~> source ./bin/activate
|
||||
|
||||
@ -166,14 +164,14 @@ Install JavaScript modules:
|
||||
|
||||
~> make init
|
||||
|
||||
Integration without previous optimzation:
|
||||
Integration without previous optimization:
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<script src="/js/config.js"></script>
|
||||
<script data-main="/js/embed" src="/js/components/requirejs/require.js"></script>
|
||||
|
||||
Optimization
|
||||
Optimization:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@ Quickstart
|
||||
==========
|
||||
|
||||
Assuming you have successfully :doc:`installed <install>` Isso, here's
|
||||
a quickstart quide that covers common setups. Sections covered:
|
||||
a quickstart quide that covers the most common setup. Sections covered:
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
@ -12,15 +12,14 @@ a quickstart quide that covers common setups. Sections covered:
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
You must provide a custom configuration. Most default parameters are useful for
|
||||
development, not persistence. The two most important options are `dbpath` to
|
||||
set the location of your database and your website's name `host` where you want
|
||||
to comment on:
|
||||
You must provide a custom configuration to set `dbpath` (your database
|
||||
location) and `host` (a list of websites for CORS_). All other options have
|
||||
sane defaults.
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[general]
|
||||
; database location, check permissions, created if not exists
|
||||
; database location, check permissions, automatically created if not exists
|
||||
dbpath = /var/lib/isso/comments.db
|
||||
; your website or blog (not the location of Isso!)
|
||||
host = http://example.tld/
|
||||
@ -36,9 +35,9 @@ Note, that multiple, *different* websites are **not** supported in a single
|
||||
configuration. To serve comments for diffent websites, refer to
|
||||
:ref:`Multiple Sites <configure-multiple-sites>`.
|
||||
|
||||
You moderate Isso through signed URLs sent by email or logged. By default,
|
||||
comments are accepted and immediately shown to other users. To enable
|
||||
moderation queue, add:
|
||||
The moderation is done with signed URLs sent by email or logged to stdout.
|
||||
By default, comments are accepted and immediately shown to other users. To
|
||||
enable moderation queue, add:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
@ -56,8 +55,8 @@ URLs for activation and deletion:
|
||||
[smtp]
|
||||
; SMTP settings
|
||||
|
||||
For more details, see :doc:`server <configuration/server>` and
|
||||
:doc:`client <configuration/client>` configuration.
|
||||
For more options, see :doc:`server <configuration/server>` and :doc:`client
|
||||
<configuration/client>` configuration.
|
||||
|
||||
Migration
|
||||
---------
|
||||
@ -67,13 +66,17 @@ your website, click on *Discussions* and select the *Export* tab. You'll
|
||||
receive an email with your comments. Unfortunately, Disqus does not export
|
||||
up- and downvotes.
|
||||
|
||||
To import existing comments, run Isso with your new configuration file:
|
||||
To import existing comments, run Isso with your configuration file:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
~> isso -c /path/to/isso.cfg import user-2013-09-02T11_39_22.971478-all.xml
|
||||
[100%] 53 threads, 192 comments
|
||||
|
||||
Migration from WordPress_ is not possible, yet (WordPress does not export
|
||||
comments). As a workaround, install the Disqus plugin, export to Disqus and
|
||||
then migrate to Isso.
|
||||
|
||||
.. _Disqus: <https://disqus.com/>
|
||||
|
||||
|
||||
|
||||
@ -1,2 +0,0 @@
|
||||
Usage
|
||||
=====
|
||||
@ -15,9 +15,9 @@
|
||||
<ul>
|
||||
<li>
|
||||
<p><strong>Create, Edit and Remove Comments</strong></p>
|
||||
<p>Commenters can edit or delete their own comments (within
|
||||
15 minutes by default).</p>
|
||||
<p>Comments in moderation queue are not publicly visible until
|
||||
<p>Users can edit or delete own comments (within 15 minutes by
|
||||
default).</p>
|
||||
<p>Comments in moderation queue are not publicly visible before
|
||||
activation.</p>
|
||||
</li>
|
||||
<li>
|
||||
@ -30,8 +30,8 @@
|
||||
</li>
|
||||
<li>
|
||||
<p><strong>client-side JavaScript</strong></p>
|
||||
<p>Embed a single JS file, 52kb (16kb gzipped) and you are
|
||||
done.</p>
|
||||
<p>Embed a single JS file, 51kb (16.5kb gzipped) and you are
|
||||
done.</p>
|
||||
<p>Supports Firefox, Safari, Chrome and IE10.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user