setup: avoid setuptools 67 - it can't handle celery's broken pytz dependency

With setuptools 67 or later, launching Kallithea fails as:

$ gearbox serve -c my.ini --reload
15:56:54,111 ERROR [gearbox] Expected closing RIGHT_PARENTHESIS
pytz (>dev)
~^

The `packaging` vendored in setuptools cannot handle the broken syntax
`Requires-Dist: pytz (>dev)` in
venv/lib/python3.11/site-packages/celery-5.0.5.dist-info/METADATA .

The old celery version currently used by Kallithea is wrong, and setuptools has
moved on after a reasonable grace period. We thus have to work around and avoid
latest setuptools.

See https://github.com/pypa/setuptools/issues/3889 .

docs: fix broken ref

7982eac0703d removed too much.

docs: drop documentation for installing without virtualenv

Installing globally as root require an unjustified trust in our build/install
process ... and makes it very hard to uninstall or clean up.

Installing as a user is slightly better but also more error-prone and not
recommended.

Those who really want to do it and know how to do it also don't need this
description.

docs: clarify the idea of best practice of installing in srv

This was introduced in 03bbd33bc084 as it seems like the best location based on
Filesystem Hierarchy Standard.

docs: when using venv with a clone, recommend using 'venv' as location

Avoid having the odd inconsistent location ../kallithea-venv to care about.

For good or bad, this might change how it is feasible to grep. I usually make
sure to only search tracked files:
grep Foo `hg mani`

docs: give "File system location" overview

Also make some other adjustments for consistency.

docs: fix display of 'note' in installation

Due to insufficient indentation on some lines, the note was displayed
incorrectly.

py3: officially support Python 3

All tests pass and no known regressions.

docs: clean up installation of optional dependencies

Install them together with Kallithea, to make things simpler, and make sure all
constraints are handled correctly.

docs: recommend --upgrade for all pip installations in a virtualenv

As suggested by Mads Kiilerich.

Don't recommend this practice when no virtualenv is used, i.e. root
installation or --user installation: in this case upgrading existing packages
may be too disruptive. The user can still add it manually if he so chooses.

setup: don't use setuptools 34 - it has indirect conflicts with the celery version supported on the stable branch (Issue #266)

Setuptools==34 requires packaging>=16.8 which has an unconstrained requirement
of pyparsing ... but actually it doesn't work with pyparsing==1.5.7 ... which
is required by celery<2.3 ... which this version of Kallithea requires.

Celery has been upgraded on the development branch but we don't want to do that
on the stable branch.

docs: remove some references to Pylons

These references are either not used, or do not provide value.
The Windows installation and email pages still references documents from the
Pylons website -- alternative pages from Turbogears2 need to be found.

docs: use ., not source, as the user isn't guaranteed to have it

Even though bash is the default shell nearly everywhere, a restricted
user running Kallithea doesn't necessarily have it as the default,
so better use POSIX-compatible . command. Besided, it's also shorter.

docs: add information about extra dependencies we now need

We have always needed some development packages, but never said
that explicitly. Now that bcrypt also requires libffi-dev, we
should mention that.

docs: restructure Kallithea upgrade instructions

This creates a separate "Upgrading Kallithea" section, instead of trying
(and failing) to repeat the same information for each installation page.
Trying to maintain upgrade instructions for each installation method was
perhaps overly ambitious. In practice, only the Linux instructions were
up-to-date.

(Incidentally, this is kind of a throwback to Kallithea 0.1, which also
had a separate upgrade section.)

docs: add advice of upgrading pip and setuptools in new virtualenvs

Withtout this, the new virtualenv might have setuptools version 12 while the
URLObject dependency mock fails because it requires setuptools>=17.1 .

docs: consistent spacing around headings

Start out with 2 empty lines before/after for top level, decrease for deeper
levels.

docs: cleanup of casing, markup and spacing of headings

Mostly stuff found and fixed by Søren, extracted here to separate things.

Other uses of title casing might be debatable, but here it was just a few
documentation headings that clearly were inconsistent with the majority.

i18n: don't include .mo files in the repo - build them on demand

(We do however keep the english .mo for now to preserve backwards
compatibility.)

docs: move all instructions on Celery to Setup

Instead of having some info on Celery in both Installation and Setup, move
everything to Setup and do some rewrite.

Additionally, update some outdated URLs and remove unused link targets.

docs/installation: clarify and reorder alternative installation methods

- Add an introduction describing the different installation methods and their
pros/cons.

- Clarify that Python 3.x is not currently supported.

- Move standard pip install method as last method, and rename as also in
virtualenv we are installing from Python Package Index.

docs/installation: add section on installation from repository source

As we actually recommend this method, describe it as first option in the
installation instructions.

docs: rework stuff

The existing docs were far from how we wanted it to be. There was so much to do
and it is not feasible to do that cleanup it in clean patches.

Instead, I took a sweep through the docs and changed what I thought could
benefit from a change: structure, examples, advices, language, markup, content,
etc.

Fixes for release 1.1.4
Docs updates

fixes few bugs
- fixed #53 python2.5 incompatible enumerate calls
- fixed #52 disable mercurial extension for web
- fixed #51 deleting repositories don't delete it's dependent objects
- small css updated