From 5f990e36976ec2dc758af48ac99f0b71c1bd41ad Mon Sep 17 00:00:00 2001 From: Martin Zimmermann Date: Mon, 13 Jan 2014 19:06:03 +0100 Subject: [PATCH] link example cfg, fix markup errors and show content table, closes #52 and also reword a few paragraphs as suggested via mail. --- docs/docs/configuration/server.rst | 4 +++- docs/docs/index.rst | 9 ++++++++ docs/docs/install.rst | 11 ++++++--- docs/docs/quickstart.rst | 30 ++++++++++++++++--------- docs/{example.conf => isso.example.cfg} | 0 5 files changed, 40 insertions(+), 14 deletions(-) rename docs/{example.conf => isso.example.cfg} (100%) diff --git a/docs/docs/configuration/server.rst b/docs/docs/configuration/server.rst index 67be002..5d12193 100644 --- a/docs/docs/configuration/server.rst +++ b/docs/docs/configuration/server.rst @@ -2,7 +2,9 @@ Server Configuration ==================== The Isso configuration file is an `INI-style`__ textfile. It reads integers, -booleans and strings. Below is a basic example: +booleans, strings and lists. Here's the default isso configuration: +:download:`isso.example.cfg `. A basic configuration from +scratch looks like this: .. code-block:: ini diff --git a/docs/docs/index.rst b/docs/docs/index.rst index 6fb5692..3c6d7b9 100644 --- a/docs/docs/index.rst +++ b/docs/docs/index.rst @@ -5,6 +5,15 @@ 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. +Documentation overview: + +.. toctree:: + :maxdepth: 1 + + install + quickstart + troubleshooting + What's Isso? ------------ diff --git a/docs/docs/install.rst b/docs/docs/install.rst index c3f028f..d83b5b1 100644 --- a/docs/docs/install.rst +++ b/docs/docs/install.rst @@ -6,15 +6,20 @@ Requirements: - Python 2.6, 2.7 or 3.3 - a working C compiler -Install Isso with PIP_: +Install Isso with `pip `_: .. code-block:: sh ~> pip install isso -.. _PIP: http://www.pip-installer.org/en/latest/ +`Dont't have pip `_? -Init scripts: +.. code-block:: sh + + ~> easy_install isso # cross your fingers + +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): - SystemD: https://github.com/jgraichen/debian-isso/blob/master/debian/isso.service - SysVinit: https://github.com/jgraichen/debian-isso/blob/master/debian/isso.init diff --git a/docs/docs/quickstart.rst b/docs/docs/quickstart.rst index 514f006..12850a1 100644 --- a/docs/docs/quickstart.rst +++ b/docs/docs/quickstart.rst @@ -2,20 +2,25 @@ Quickstart ========== Assuming you have successfully :doc:`installed ` Isso, here's -a quickstart quide that covers common setups. +a quickstart quide that covers common setups. Sections covered: + +.. contents:: + :local: + :depth: 1 Configuration ------------- You must provide a custom configuration. Most default parameters are useful for -development, not persistence. Two most important options are `dbpath` to set -the location of your database and `host` which is your website: +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: .. code-block:: ini [general] - ; database location, check permissions + ; database location, check permissions, created if not exists dbpath = /var/lib/isso/comments.db ; your website or blog (not the location of Isso!) host = http://example.tld/ @@ -51,6 +56,8 @@ URLs for activation and deletion: [smtp] ; SMTP settings +For more details, see :doc:`server ` and +:doc:`client ` configuration. Migration --------- @@ -107,6 +114,9 @@ configuration looks like this: } } +Integration +----------- + Now, you embed Isso to your website: .. code-block:: html @@ -129,13 +139,13 @@ a comment to see if the setup works. If not, see :doc:`troubleshooting`. Deployment ---------- -Isso ships with a built-in web server, which is useful for the initial setup. -But it is not recommended to use the built-in web server for production. A few -WSGI servers are supported out-of-the-box: +Isso ships with a built-in web server, which is useful for the initial setup +and may be used in production for low-traffic sites (up to 20 requests per +second). It is recommended to use a "real" WSGI server to run Isso, e.g: - * gevent_, coroutine-based network library - * uWSGI_, full-featured uWSGI server - * gunicorn_, Python WSGI HTTP Server for UNIX +* gevent_, coroutine-based network library +* uWSGI_, full-featured uWSGI server +* gunicorn_, Python WSGI HTTP Server for UNIX .. _gevent: http://www.gevent.org/ .. _uWSGI: http://uwsgi-docs.readthedocs.org/en/latest/ diff --git a/docs/example.conf b/docs/isso.example.cfg similarity index 100% rename from docs/example.conf rename to docs/isso.example.cfg