--- a/docs/setup.rst	Tue Mar 31 16:25:49 2015 +0000
+++ b/docs/setup.rst	Tue Mar 31 22:15:38 2015 +0200
@@ -9,19 +9,19 @@
 --------------------
 
 First, you will need to create a Kallithea configuration file. Run the
-following command to do this::
+following command to do so::
 
     paster make-config Kallithea my.ini
 
-- This will create the file `my.ini` in the current directory. This
-  configuration file contains the various settings for Kallithea, e.g proxy
-  port, email settings, usage of static files, cache, Celery settings and
-  logging.
+This will create the file ``my.ini`` in the current directory. This
+configuration file contains the various settings for Kallithea, e.g.,
+proxy port, email settings, usage of static files, cache, Celery
+settings, and logging.
 
 
 Next, you need to create the databases used by Kallithea. It is recommended to
 use PostgreSQL or SQLite (default). If you choose a database other than the
-default ensure you properly adjust the database URL in your my.ini
+default, ensure you properly adjust the database URL in your ``my.ini``
 configuration file to use this other database. Kallithea currently supports
 PostgreSQL, SQLite and MySQL databases. Create the database by running
 the following command::
@@ -34,46 +34,50 @@
 and password for the initial admin account which ``setup-db`` sets
 up for you.
 
-setup process can be fully automated, example for lazy::
+The setup process can be fully automated, example for lazy::
 
     paster setup-db my.ini --user=nn --password=secret --email=nn@your.kallithea.server --repos=/srv/repos
 
 
-- The ``setup-db`` command will create all of the needed tables and an
-  admin account. When choosing a root path you can either use a new empty
-  location, or a location which already contains existing repositories. If you
-  choose a location which contains existing repositories Kallithea will
-  add all of the repositories at the chosen location to its database.
-  (Note: make sure you specify the correct path to the root).
-- Note: the given path for Mercurial_ repositories **must** be write accessible
-  for the application. It's very important since the Kallithea web interface
-  will work without write access, but when trying to do a push it will
-  eventually fail with permission denied errors unless it has write access.
+The ``setup-db`` command will create all of the needed tables and an
+admin account. When choosing a root path you can either use a new
+empty location, or a location which already contains existing
+repositories. If you choose a location which contains existing
+repositories Kallithea will add all of the repositories at the chosen
+location to its database.  (Note: make sure you specify the correct
+path to the root).
 
-You are now ready to use Kallithea, to run it simply execute::
+.. note:: the given path for Mercurial_ repositories **must** be write
+          accessible for the application. It's very important since
+          the Kallithea web interface will work without write access,
+          but when trying to do a push it will fail with permission
+          denied errors unless it has write access.
+
+You are now ready to use Kallithea. To run it simply execute::
 
     paster serve my.ini
 
-- This command runs the Kallithea server. The web app should be available at the
-  127.0.0.1:5000. This ip and port is configurable via the my.ini
+- This command runs the Kallithea server. The web app should be available at
+  http://127.0.0.1:5000. This ip and port is configurable via the my.ini
   file created in previous step
 - Use the admin account you created above when running ``setup-db``
   to login to the web app.
 - The default permissions on each repository is read, and the owner is admin.
   Remember to update these if needed.
-- In the admin panel you can toggle LDAP, anonymous, permissions settings. As
-  well as edit more advanced options on users and repositories
+- In the admin panel you can toggle LDAP, anonymous, and permissions
+  settings, as well as edit more advanced options on users and
+  repositories
 
-Optionally users can create `rcextensions` package that extends Kallithea
+Optionally users can create an ``rcextensions`` package that extends Kallithea
 functionality. To do this simply execute::
 
     paster make-rcext my.ini
 
-This will create `rcextensions` package in the same place that your `ini` file
-lives. With `rcextensions` it's possible to add additional mapping for whoosh,
-stats and add additional code into the push/pull/create/delete repo hooks.
-For example for sending signals to build-bots such as Jenkins.
-Please see the `__init__.py` file inside `rcextensions` package
+This will create an ``rcextensions`` package in the same place that your ``ini`` file
+lives. With ``rcextensions`` it's possible to add additional mapping for whoosh,
+stats and add additional code into the push/pull/create/delete repo hooks,
+for example, for sending signals to build-bots such as Jenkins.
+Please see the ``__init__.py`` file inside ``rcextensions`` package
 for more details.
 
 
@@ -90,39 +94,41 @@
 as the project. When using repository groups, each group is a subdirectory.
 This allows you to easily use ssh for accessing repositories.
 
-In order to use ssh you need to make sure that your web-server and the users
+In order to use ssh you need to make sure that your web server and the users'
 login accounts have the correct permissions set on the appropriate directories.
-(Note that these permissions are independent of any permissions you have set up
-using the Kallithea web interface.)
+
+.. note:: These permissions are independent of any permissions you
+          have set up using the Kallithea web interface.
 
-If your main directory (the same as set in Kallithea settings) is for example
-set to **/srv/repos** and the repository you are using is named `kallithea`, then
-to clone via ssh you should run::
+If your main directory (the same as set in Kallithea settings) is for
+example set to ``/srv/repos`` and the repository you are using is
+named ``kallithea``, then to clone via ssh you should run::
 
     hg clone ssh://user@server.com//srv/repos/kallithea
 
-Using other external tools such as mercurial-server_ or using ssh key based
+Using other external tools such as mercurial-server_ or using ssh key-based
 authentication is fully supported.
 
-Note: In an advanced setup, in order for your ssh access to use the same
-permissions as set up via the Kallithea web interface, you can create an
-authentication hook to connect to the Kallithea db and runs check functions for
-permissions against that.
+.. note:: In an advanced setup, in order for your ssh access to use
+          the same permissions as set up via the Kallithea web
+          interface, you can create an authentication hook to connect
+          to the Kallithea db and run check functions for permissions
+          against that.
 
 Setting up Whoosh full text search
 ----------------------------------
 
-The whoosh index can be build by using the paster
+The whoosh index can be built by using the paster
 command ``make-index``. To use ``make-index`` you must specify the configuration
 file that stores the location of the index. You may specify the location of the
-repositories (`--repo-location`).  If not specified, this value is retrieved
+repositories (``--repo-location``).  If not specified, this value is retrieved
 from the Kallithea database.
 It is also possible to specify a comma separated list of
-repositories (`--index-only`) to build index only on chooses repositories
+repositories (``--index-only``) to build index only on chooses repositories
 skipping any other found in repos location
 
-You may optionally pass the option `-f` to enable a full index rebuild. Without
-the `-f` option, indexing will run always in "incremental" mode.
+You may optionally pass the option ``-f`` to enable a full index rebuild. Without
+the ``-f`` option, indexing will run always in "incremental" mode.
 
 For an incremental index build use::
 
@@ -133,14 +139,14 @@
     paster make-index my.ini -f
 
 
-building index just for chosen repositories is possible with such command::
+Building an index for just selected repositories is possible with such command::
 
     paster make-index my.ini --index-only=vcs,kallithea
 
 
-In order to do periodical index builds and keep your index always up to date.
-It's recommended to do a crontab entry for incremental indexing.
-An example entry might look like this::
+In order to do periodic index builds and keep your index always up to
+date, it is recommended to use a crontab entry.  An example entry
+might look like this::
 
     /path/to/python/bin/paster make-index /path/to/kallithea/my.ini
 
@@ -149,8 +155,8 @@
 available. The indexing daemon checks for any removed files and removes them
 from index.
 
-If you want to rebuild index from scratch, you can use the `-f` flag as above,
-or in the admin panel you can check `build from scratch` flag.
+If you want to rebuild the index from scratch, you can use the ``-f`` flag as above,
+or in the admin panel you can check the "build from scratch" flag.
 
 
 Setting up LDAP support
@@ -158,15 +164,15 @@
 
 Kallithea supports LDAP authentication. In order
 to use LDAP, you have to install the python-ldap_ package. This package is
-available via pypi, so you can install it by running
+available via pypi, so you can install it by running::
 
     pip install python-ldap
 
-.. note::
-   python-ldap requires some certain libs on your system, so before installing
-   it check that you have at least `openldap`, and `sasl` libraries.
+.. note:: ``python-ldap`` requires some libraries to be installed on
+          your system, so before installing it check that you have at
+          least the ``openldap`` and ``sasl`` libraries.
 
-LDAP settings are located in Admin->LDAP section.
+LDAP settings are located in the Admin->LDAP section.
 
 Here's a typical LDAP setup::
 
@@ -190,7 +196,7 @@
  Last Name Attribute  = lastName
  E-mail Attribute     = mail
 
-If your user groups are placed in a Organisation Unit (OU) structure the Search Settings configuration differs::
+If your user groups are placed in an Organisation Unit (OU) structure, the Search Settings configuration differs::
 
  Search settings
  Base DN              = DC=host,DC=example,DC=org
@@ -433,25 +439,26 @@
 -------------------------------
 
 Kallithea provides a simple integration with issue trackers. It's possible
-to define a regular expression that will fetch issue id stored in commit
-messages and replace that with an url to this issue. To enable this simply
-uncomment following variables in the ini file::
+to define a regular expression that will fetch an issue id stored in a commit
+messages and replace that with a URL to the issue. To enable this simply
+uncomment the following variables in the ini file::
 
     issue_pat = (?:^#|\s#)(\w+)
     issue_server_link = https://myissueserver.com/{repo}/issue/{id}
     issue_prefix = #
 
-`issue_pat` is the regular expression describing which strings in
+``issue_pat`` is the regular expression describing which strings in
 commit messages will be treated as issue references. A match group in
 parentheses should be used to specify the actual issue id.
 
-The default expression matches issues in the format '#<number>', e.g. '#300'.
+The default expression matches issues in the format ``#<number>``, e.g., ``#300``.
 
-Matched issues are replaced with the link specified as `issue_server_link`
-{id} is replaced with issue id, and {repo} with repository name.
-Since the # is stripped away, `issue_prefix` is prepended to the link text.
-`issue_prefix` doesn't necessarily need to be #: if you set issue
-prefix to ISSUE- this will generate a URL in format::
+Matched issues are replaced with the link specified as
+``issue_server_link`` ``{id}`` is replaced with issue id, and
+``{repo}`` with the repository name.  Since the # is stripped away,
+``issue_prefix`` is prepended to the link text.  ``issue_prefix`` doesn't
+necessarily need to be ``#``: if you set issue prefix to ``ISSUE-`` this will
+generate a URL in the format::
 
   <a href="https://myissueserver.com/example_repo/issue/300">ISSUE-300</a>
 
@@ -471,25 +478,25 @@
 Hook management
 ---------------
 
-Hooks can be managed in similar way to this used in .hgrc files.
-To access hooks setting click `advanced setup` on Hooks section of Mercurial
-Settings in Admin.
+Hooks can be managed in similar way to that used in ``.hgrc`` files.
+To access hooks setting click `advanced setup` in the `Hooks` section
+of Mercurial Settings in Admin.
 
-There are 4 built in hooks that cannot be changed (only enable/disable by
-checkboxes on previos section).
-To add another custom hook simply fill in first section with
-<name>.<hook_type> and the second one with hook path. Example hooks
-can be found at *kallithea.lib.hooks*.
+There are four built in hooks that cannot be changed (only enabled/disabled by
+checkboxes in the previous section).
+To add another custom hook simply fill in the first section with
+``<name>.<hook_type>`` and the second one with hook path. Example hooks
+can be found in ``kallithea.lib.hooks``.
 
 
 Changing default encoding
 -------------------------
 
 By default, Kallithea uses UTF-8 encoding.
-It is configurable as `default_encoding` in the .ini file.
+This is configurable as ``default_encoding`` in the .ini file.
 This affects many parts in Kallithea including user names, filenames, and
-encoding of commit messages. In addition Kallithea can detect if `chardet`
-library is installed. If `chardet` is detected Kallithea will fallback to it
+encoding of commit messages. In addition Kallithea can detect if the ``chardet``
+library is installed. If ``chardet`` is detected Kallithea will fallback to it
 when there are encode/decode errors.
 
 
@@ -511,9 +518,9 @@
 The use of Celery is configured in the Kallithea ini configuration file.
 To enable it, simply set::
 
- use_celery = true
+  use_celery = true
 
-and add or change the celery.* and broker.* configuration variables.
+and add or change the ``celery.*`` and ``broker.*`` configuration variables.
 
 Remember that the ini files use the format with '.' and not with '_' like
 Celery. So for example setting `BROKER_HOST` in Celery means setting
@@ -536,10 +543,10 @@
 Alternatively, you can use some special configuration settings to control
 directly which scheme/protocol Kallithea will use when generating URLs:
 
-- With `https_fixup = true`, the scheme will be taken from the HTTP_X_URL_SCHEME,
-  HTTP_X_FORWARDED_SCHEME or HTTP_X_FORWARDED_PROTO HTTP header (default 'http').
-- With `force_https = true` the default will be 'https'.
-- With `use_htsts = true`, it will set Strict-Transport-Security when using https.
+- With ``https_fixup = true``, the scheme will be taken from the ``HTTP_X_URL_SCHEME``,
+  ``HTTP_X_FORWARDED_SCHEME`` or ``HTTP_X_FORWARDED_PROTO HTTP`` header (default ``http``).
+- With ``force_https = true`` the default will be ``https``.
+- With ``use_htsts = true``, it will set ``Strict-Transport-Security`` when using https.
 
 Nginx virtual host example
 --------------------------
@@ -671,7 +678,7 @@
     </Location>
 
 Besides the regular apache setup you will need to add the following line
-into [app:main] section of your .ini file::
+into ``[app:main]`` section of your .ini file::
 
     filter-with = proxy-prefix
 
@@ -682,7 +689,7 @@
     prefix = /<someprefix>
 
 
-then change <someprefix> into your chosen prefix
+then change ``<someprefix>`` into your chosen prefix
 
 Apache's WSGI config
 --------------------
@@ -700,9 +707,9 @@
     a2enmod wsgi
 
 - Create a wsgi dispatch script, like the one below. Make sure you
-  check the paths correctly point to where you installed Kallithea
+  check that the paths correctly point to where you installed Kallithea
   and its Python Virtual Environment.
-- Enable the WSGIScriptAlias directive for the wsgi dispatch script,
+- Enable the ``WSGIScriptAlias`` directive for the WSGI dispatch script,
   as in the following example. Once again, check the paths are
   correctly specified.
 
@@ -714,7 +721,7 @@
     WSGIScriptAlias / /srv/kallithea/dispatch.wsgi
     WSGIPassAuthorization On
 
-Or if using a dispatcher wsgi script with proper virtualenv activation::
+Or if using a dispatcher WSGI script with proper virtualenv activation::
 
     WSGIDaemonProcess kallithea processes=1 threads=4
     WSGIScriptAlias / /srv/kallithea/dispatch.wsgi
@@ -723,15 +730,15 @@
 
 .. note::
    When running apache as root, please make sure it doesn't run Kallithea as
-   root, for examply by adding: `user=www-data group=www-data` to the configuration.
+   root, for examply by adding: ``user=www-data group=www-data`` to the configuration.
 
 .. note::
    If running Kallithea in multiprocess mode,
-   make sure you set `instance_id = \*` in the configuration so each process
-   gets it's own cache invalidationkey.
+   make sure you set ``instance_id = *`` in the configuration so each process
+   gets it's own cache invalidation key.
 
 
-Example wsgi dispatch script::
+Example WSGI dispatch script::
 
     import os
     os.environ["HGENCODING"] = "UTF-8"
@@ -767,7 +774,8 @@
 Other configuration files
 -------------------------
 
-Some example init.d scripts can be found in init.d directory: https://kallithea-scm.org/repos/kallithea/files/tip/init.d/
+Some example init.d scripts can be found in the ``init.d`` directory:
+https://kallithea-scm.org/repos/kallithea/files/tip/init.d/ .
 
 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
 .. _python: http://www.python.org/