Commit 52708658 authored by Aurélien Bompard's avatar Aurélien Bompard

Prepare for release

parent 179dd8ac
*.egg-info
doc/_build
doc/_static
dist
......@@ -5,3 +5,6 @@
kittystore
logs
*.egg-info
doc/_build
doc/_static
/dist
Aamir Khan <syst3m.w0rm@gmail.com>
Pierre-Yves Chibon <pingou@pingoured.fr>
Aurelien Bompard <aurelien@bompard.org>
This diff is collapsed.
include AUTHORS.txt COPYING.txt pylintrc distribute_setup.py
# http://bruno.im/2010/may/05/packaging-django-reusable-app/
recursive-include hyperkitty *.py *.html *.js
graft hyperkitty/static
include doc/conf.py doc/Makefile doc/*.rst
===================================
============================================
HyperKitty - Archiver for for GNU Mailman v3
===================================
============================================
HyperKitty is an open source Django application under development. It aims to provide web interface to access GNU Mailman archives.
HyperKitty is an open source Django application under development. It aims at
providing a web interface to access GNU Mailman archives.
The code is available from: http://bzr.fedorahosted.org/bzr/hyperkitty/
Installation
============
The documentation is located in the "doc" subfolder. It can be generated in
various formats thanks to `Sphinx`_. To generate the HTML documentation, run
the following command::
1. git clone https://github.com/syst3mw0rm/hyperkitty
2. cd hyperkitty
3. python setup.py develop
4. Clone KittyStore and Load archive data into postgresql using kittystore (https://github.com/pypingou/kittystore)
5. Create symlink kittystore using **ln -s {path-to-kittystore}/kittystore/ kittystore**
6. Install hk-app (https://github.com/syst3mw0rm/hk-app)
make -C doc html
Dependencies
============
The HTML files will be available in the ``doc/_build/html`` directory.
Hyperkitty dependencies
-----------------------
* Django==1.4
* URLObject==2.0.2
* django-gravatar==0.1.0
* django-social-auth==0.7.0
* djangorestframework==0.3.3
* httplib2==0.7.4
* oauth2==1.5.211
* psycopg2==2.4.5
* python-openid==2.2.5
* wsgiref==0.1.2
.. _Sphinx: http://sphinx-doc.org
kittystore dependencies
-----------------------
* SQLAlchemy==0.7.8
License
=======
License
========
HyperKitty is licensed under the `GPL v3.0`_
.. _GPL v3.0: http://www.gnu.org/licenses/gpl-3.0.html
HyperKitty is licensed under the `GPL v3.0`_
This diff is collapsed.
......@@ -41,7 +41,7 @@ master_doc = 'index'
# General information about the project.
project = u'HyperKitty'
copyright = u'2012, Mailman Coders'
copyright = u'2012, HyperKitty Developers'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
......@@ -64,7 +64,7 @@ release = '0.1'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']
exclude_patterns = ['_build', 'database.rst']
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
......
Setting up the databases
========================
Now you can create the KittyStore and HyperKitty databases, and set their
access URLs in ``hyperkitty_standalone/settings.py`` (or
``hyperkitty_standalone/settings_local.py``). HyperKitty's database can be
created using the following command::
python manage.py syncdb
KittyStore's database will be created automatically on first access.
Then, you can run ``kittystore-import`` to import existing archives into the
mailman database. Thoses archives can be downloaded by a script similar to the
``get_mbox.py`` script provided in the ``kittystore`` module. If you're
installing hyperkitty on the machine which hosted the previous version of
mailman, the archived are already available locally and you can use them
directly.
===========
Development
===========
Communication channels
======================
Hang out on IRC and ask questions on ``#mailman`` or join the mailing list
``hyperkitty-devel@lists.fedorahosted.org``.
Setting up Hyperkitty for development
=====================================
The recommanded way to develop on HyperKitty is to use VirtualEnv. It will
create an isolated Python environment where you can add HyperKitty and its
dependencies without messing up your system Python install.
First, create the virtualenv and activate it::
virtualenv venv_hk
source venv_hk/bin/activate
Then download the components of HyperKitty::
git clone git://github.com/pypingou/kittystore.git
cd kittystore
python setup.py develop
cd ..
bzr branch bzr://bzr.fedorahosted.org/bzr/hyperkitty/hyperkitty
cd hyperkitty
python setup.py develop
cd ..
bzr branch bzr://bzr.fedorahosted.org/bzr/hyperkitty/hyperkitty_standalone
.. Setting up the databases
.. include:: database.rst
Running HyperKitty
==================
If you're coding on HyperKitty, you can use Django's integrated web server.
It can be run with the following command::
cd hyperkitty_standalone
python manage.py runserver
.. warning::
You should use the development server only locally. While it's possible to
make your site publicly available using the dev server, you should never
do that in a production environment.
Testing
=======
Use the following command::
python manage.py test hyperkitty
All test modules reside in the ``hyperkitty/tests`` directory
and this is where you should put your own tests, too. To make the django test
runner find your tests, make sure to add them to the folder's ``__init__.py``:
================
News / Changelog
================
======================================
Welcome to HyperKitty's documentation!
======================================
Copyright (C) 2012 by the Free Software Foundation, Inc.
The HyperKitty Django app provides a web interface to access GNU Mailman v3
archives.
The project page is https://fedorahosted.org/hyperkitty/ and the code is
available from http://bzr.fedorahosted.org/bzr/hyperkitty/ .
The authors are listed in the ``AUTHORS.txt`` file.
Contents:
.. toctree::
:maxdepth: 1
news.rst
install.rst
development.rst
The HyperKitty Django app provides a web interface to access GNU Mailman v3
Archives.
Copyright (C) 2012 by the Free Software Foundation, Inc.
HyperKitty is free software: you can redistribute it and/or
modify it under the terms of the GNU General Public License as
......@@ -19,17 +33,3 @@ General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with HyperKitty. If not, see <http://www.gnu.org/licenses/>.
0.1 alpha 1
============
(2012-XX-XX)
Initial release of HyperKitty.
* login using django user account / browserid / google openid / yahoo openid
* rate messages
* use bootstrap.css for stylesheets
* show basic list info and metrics
* show basic user profile
* Add tags to message threads
============
Installation
============
.. note::
This installation guide covers HyperKitty, the web user interface to access
GNU Mailman v3 Archives. To install GNU Mailman follow the instructions in
the documentation: http://packages.python.org/mailman/
Install the code
================
Install the HyperKitty package and its dependencies with the following
commands::
sudo pip install -r requirements.txt
sudo python setup.py install
Setup your django project
=========================
You now have installed the necessary packages but you still need to setup the
Django site (project).
First, get the project directory from the source code management system::
bzr branch bzr://bzr.fedorahosted.org/bzr/hyperkitty/hyperkitty_standalone
Second, change the database setting in ``hyperkitty_standalone/settings.py`` to
your preferred database. HyperKitty uses two databases, one to store the metadata
and other to store the emails. Edit this file to reflect the correct database
credentials. The configuration variables are ``DATABASES`` (at the top of the
file) and ``KITTYSTORE_URL`` (at the bottom).
.. note::
Detailed information on how to use different database engines can be found
in the `Django documentation`_.
.. _Django documentation: https://docs.djangoproject.com/en/1.4/ref/settings/#databases
Third, you must setup the database tables, and the admin account (you will be
prompted for it).
.. Setting up the databases
.. include:: database.rst
Running HyperKitty on Apache with mod_wsgi
==========================================
.. note::
This guide assumes that you know how to setup a VirtualHost with Apache.
If you are using SQLite, the ``.db`` file as well as its folder need to be
writable by the web server.
Edit ``hyperkitty_standalone/hyperkitty.apache.conf`` to point to your source
code location.
Add following line to your apache/httpd configuration file::
Include "/{path-to-hyperkitty_standalone}/hyperkitty.apache.conf"
And reload Apache. We're almost ready. But you need to collect the static files
from HyperKitty (which resides somewhere on your pythonpath) to be able to
serve them from the site directory. All you have to do is to change into the
``hyperkitty_standalone`` directory and run::
python manage.py collectstatic
These static files will be served by Apache. You should now be all set. Try
accessing HyperKitty in your web browser.
Connecting to Mailman
=====================
To receive incoming emails from Mailman, you must add the follwing lines to
``mailman.cfg``::
[archiver.hyperkitty]
class: hyperkitty.lib.archiver.Archiver
enable: yes
configuration: /path/to/hyperkitty_standalone/hyperkitty.cfg
The ``hyperkitty.cfg`` file which path is specified by the ``configuration``
key is an additional HyperKitty-specific configuration file for which an
example is provided. See the included ``hyperkitty_standalone/hyperkitty.cfg``
file.
After having made these changes, you must restart Mailman. Check its log files
to make sure the emails are correctly archived. You should not see "``Broken
archiver: hyperkitty``" messages.
License
=======
HyperKitty is licensed under the `GPL v3.0`_
.. _GPL v3.0: http://www.gnu.org/licenses/gpl-3.0.html
================
News / Changelog
================
0.1 (alpha)
===========
(2012-11-22)
Initial release of HyperKitty.
* login using django user account / browserid / google openid / yahoo openid
* use Twitter Bootstrap for stylesheets
* show basic list info and metrics
* show basic user profile
* Add tags to message threads
This diff is collapsed.
===========
Development
===========
Contribution
========
Hang out on IRC and ask questions on #mailman or join the mailing list mailman-developers@python.org
Get the development version up and running:
1. bzr branch bzr://bzr.fedorahosted.org/bzr/hyperkitty/hyperkitty
2. cd hyperkitty
3. python setup.py develop ( this command may require sudo privileges)
4. Clone the stand alone hk-app, bzr branch bzr://bzr.fedorahosted.org/bzr/hyperkitty/hk-app
5. cd hk-app
6. python manage.py syncdb
7. python manage.py runserver
(you may need to load data in your local machine using kittystore to get it running)
Testing
=======
python manage.py test hyperkitty
All test modules reside in the ``hyperkitty/hyperkitty/tests`` directory
and this is where you should put your own tests, too. To make the django test
runner find your tests, make sure to add them to the folder's ``__init__.py``:
Welcome to HyperKitty's documentation!
======================================
Contents:
.. toctree::
:maxdepth: 1
news.rst
setup.rst
development.rst
\ No newline at end of file
============
Installation
============
.. note::
This installation guide covers HyperKitty, the web user interfaceaccess GNU Mailman v3
Archives. To install GNU Mailman follow the instructions in the documentation:
http://packages.python.org/mailman/
Install Dependencies
====================
sudo pip install -r requirements.txt
Install HyperKitty
=================
sudo python manage.py install
Setup your django project
=========================
Since you have now installed the necessary packages to run HyperKitty, it's
time to setup your Django site.
First, get the project directory from launchpad:
::
$ bzr branch bzr://bzr.fedorahosted.org/bzr/hyperkitty/hk-app
Second, change the database setting in ``postorius_standalone/settings.py`` to
your preferred database. HyperKitty uses two databases, one to store the metadata
and other to store mails. Edit this file to reflect the correct database credential.
.. note::
Detailed information on how to use different database engines can be found
in the `Django documentation`_.
.. _Django documentation: https://docs.djangoproject.com/en/1.4/ref/settings/#databases
Third, prepare the database:
::
$ cd hk-app
$ python manage.py syncdb
$ cd ..
This will create the ``.db file`` (if you are using SQLite) and will setup all the
necessary db tables. You will also be prompted to create a superuser which
will act as an admin account for HyperKitty
Running the development server
==============================
The quickest way to run HyperKitty is to just start the development server:
::
$ cd hk-app
$ python manage.py runserver
.. warning::
You should use the development server only locally. While it's possible to
make your site publicly available using the dev server, you should never
do that in a production environment.
Running HyperKitty on Apache with mod_wsgi
=========================================
.. note::
This guide assumes that you know how to setup a VirtualHost with Apache.
If you are using SQLite, the ``.db`` file as well as its folder need to be
writable by the web server.
Edit ``apache/apache_django_wsgi.conf`` to point to your source code location.
Add following line to your apache/httpd configuration file
::
Include "/{path-to-hk-app}/apache/apache_django_wsgi.conf"
We're almost ready. But you need to collect the static files from HyperKitty
(which resides somewhere on your pythonpath) to be able to serve them from the
site directory. All you have to do is to change into the
``hk-app`` directory and run:
::
$ python manage.py collectstatic
================
News / Changelog
================
Copyright (C) 2012 by the Free Software Foundation, Inc.
The HyperKitty Django app provides a web interface to access GNU Mailman v3
Archives.
HyperKitty is free software: you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, version 3 of the License.
HyperKitty is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with HyperKitty. If not, see <http://www.gnu.org/licenses/>.
0.1 alpha 1
============
(2012-XX-XX)
Initial release of HyperKitty.
* login using django user account / browserid / google openid / yahoo openid
* rate messages
* use bootstrap.css for stylesheets
* show basic list info and metrics
* show basic user profile
* Add tags to message threads
/*
* basic.css
* ~~~~~~~~~
*
* Sphinx stylesheet -- basic theme.
*
* :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
/* -- main layout ----------------------------------------------------------- */
div.clearer {
clear: both;
}
/* -- relbar ---------------------------------------------------------------- */
div.related {
width: 100%;
font-size: 90%;
}
div.related h3 {
display: none;
}
div.related ul {
margin: 0;
padding: 0 0 0 10px;
list-style: none;
}
div.related li {
display: inline;
}
div.related li.right {
float: right;
margin-right: 5px;
}
/* -- sidebar --------------------------------------------------------------- */
div.sphinxsidebarwrapper {
padding: 10px 5px 0 10px;
}
div.sphinxsidebar {
float: left;
width: 230px;
margin-left: -100%;
font-size: 90%;
}
div.sphinxsidebar ul {
list-style: none;
}
div.sphinxsidebar ul ul,
div.sphinxsidebar ul.want-points {
margin-left: 20px;
list-style: square;
}
div.sphinxsidebar ul ul {
margin-top: 0;
margin-bottom: 0;
}
div.sphinxsidebar form {
margin-top: 10px;
}
div.sphinxsidebar input {
border: 1px solid #98dbcc;
font-family: sans-serif;
font-size: 1em;
}
img {
border: 0;
}
/* -- search page ----------------------------------------------------------- */
ul.search {
margin: 10px 0 0 20px;
padding: 0;
}
ul.search li {
padding: 5px 0 5px 20px;
background-image: url(file.png);
background-repeat: no-repeat;
background-position: 0 7px;
}
ul.search li a {
font-weight: bold;
}
ul.search li div.context {
color: #888;
margin: 2px 0 0 30px;
text-align: left;
}
ul.keywordmatches li.goodmatch a {
font-weight: bold;
}
/* -- index page ------------------------------------------------------------ */
table.contentstable {
width: 90%;
}
table.contentstable p.biglink {
line-height: 150%;
}
a.biglink {
font-size: 1.3em;
}
span.linkdescr {
font-style: italic;
padding-top: 5px;
font-size: 90%;
}
/* -- general index --------------------------------------------------------- */
table.indextable {
width: 100%;
}
table.indextable td {
text-align: left;
vertical-align: top;
}
table.indextable dl, table.indextable dd {
margin-top: 0;
margin-bottom: 0;
}
table.indextable tr.pcap {
height: 10px;
}
table.indextable tr.cap {
margin-top: 10px;
background-color: #f2f2f2;
}
img.toggler {
margin-right: 3px;
margin-top: 3px;
cursor: pointer;
}
div.modindex-jumpbox {
border-top: 1px solid #ddd;
border-bottom: 1px solid #ddd;
margin: 1em 0 1em 0;
padding: 0.4em;
}
div.genindex-jumpbox {
border-top: 1px solid #ddd;
border-bottom: 1px solid #ddd;
margin: 1em 0 1em 0;
padding: 0.4em;
}
/* -- general body styles --------------------------------------------------- */
a.headerlink {
visibility: hidden;
}
h1:hover > a.headerlink,
h2:hover > a.headerlink,
h3:hover > a.headerlink,
h4:hover > a.headerlink,
h5:hover > a.headerlink,
h6:hover > a.headerlink,
dt:hover > a.headerlink {
visibility: visible;
}
div.body p.caption {
text-align: inherit;
}