From cb36107edaaa01d89aea5d2632b658975f477f63 Mon Sep 17 00:00:00 2001 From: Martin Zimmermann Date: Mon, 28 Apr 2014 19:42:36 +0200 Subject: [PATCH] reword and clean documentation --- docs/docs/configuration/client.rst | 2 ++ docs/docs/configuration/isso.conf | 1 - docs/docs/configuration/server.rst | 4 ++-- docs/docs/index.rst | 8 ++++---- docs/docs/install.rst | 30 ++++++++++++++---------------- docs/docs/quickstart.rst | 27 +++++++++++++++------------ docs/docs/usage.rst | 2 -- docs/index.html | 10 +++++----- 8 files changed, 42 insertions(+), 42 deletions(-) delete mode 120000 docs/docs/configuration/isso.conf delete mode 100644 docs/docs/usage.rst diff --git a/docs/docs/configuration/client.rst b/docs/docs/configuration/client.rst index 17f3e2a..09e4e0f 100644 --- a/docs/docs/configuration/client.rst +++ b/docs/docs/configuration/client.rst @@ -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. diff --git a/docs/docs/configuration/isso.conf b/docs/docs/configuration/isso.conf deleted file mode 120000 index 984bd8b..0000000 --- a/docs/docs/configuration/isso.conf +++ /dev/null @@ -1 +0,0 @@ -../../../share/isso.conf \ No newline at end of file diff --git a/docs/docs/configuration/server.rst b/docs/docs/configuration/server.rst index 977dd1f..c3713b9 100644 --- a/docs/docs/configuration/server.rst +++ b/docs/docs/configuration/server.rst @@ -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 `. A basic configuration from -scratch looks like this: +`isso.conf `. A +basic configuration from scratch looks like this: .. code-block:: ini diff --git a/docs/docs/index.rst b/docs/docs/index.rst index 3c6d7b9..491dbf8 100644 --- a/docs/docs/index.rst +++ b/docs/docs/index.rst @@ -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" ------------------ diff --git a/docs/docs/install.rst b/docs/docs/install.rst index b3cdb99..1444ea1 100644 --- a/docs/docs/install.rst +++ b/docs/docs/install.rst @@ -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 `_: ~> 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 `_ compiler - Node.js, `NPM `__ and `Bower `__ 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 -Optimization +Optimization: .. code-block:: sh diff --git a/docs/docs/quickstart.rst b/docs/docs/quickstart.rst index bdc98d5..59e31ce 100644 --- a/docs/docs/quickstart.rst +++ b/docs/docs/quickstart.rst @@ -2,7 +2,7 @@ Quickstart ========== Assuming you have successfully :doc:`installed ` 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 `. -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 ` and -:doc:`client ` configuration. +For more options, see :doc:`server ` and :doc:`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: diff --git a/docs/docs/usage.rst b/docs/docs/usage.rst deleted file mode 100644 index d4b9a15..0000000 --- a/docs/docs/usage.rst +++ /dev/null @@ -1,2 +0,0 @@ -Usage -===== diff --git a/docs/index.html b/docs/index.html index 2b9ea9d..9ed4a58 100644 --- a/docs/index.html +++ b/docs/index.html @@ -15,9 +15,9 @@

  • Create, Edit and Remove Comments

    -

    Commenters can edit or delete their own comments (within - 15 minutes by default).

    -

    Comments in moderation queue are not publicly visible until +

    Users can edit or delete own comments (within 15 minutes by + default).

    +

    Comments in moderation queue are not publicly visible before activation.

  • @@ -30,8 +30,8 @@

  • client-side JavaScript

    -

    Embed a single JS file, 52kb (16kb gzipped) and you are - done.

    +

    Embed a single JS file, 51kb (16.5kb gzipped) and you are + done.

    Supports Firefox, Safari, Chrome and IE10.