development.rst 3.37 KB
Newer Older
Aurélien Bompard's avatar
Aurélien Bompard committed
1 2 3 4
===========
Development
===========

aamir khan's avatar
aamir khan committed
5 6 7 8
Building documentation
======================

The full documentation is located in the "doc" subfolder. It can be generated
9
in various formats once you have installed `Sphinx`_. To generate the HTML documentation,
aamir khan's avatar
aamir khan committed
10 11 12 13 14 15 16 17 18 19 20
run the following command::

    make -C doc html

The HTML files will be available in the ``doc/_build/html`` directory.

The documentation can also be browsed online at:
https://hyperkitty.readthedocs.org.

.. _Sphinx: http://sphinx-doc.org

Aurélien Bompard's avatar
Aurélien Bompard committed
21 22 23 24

Communication channels
======================

Sumana Harihareswara's avatar
Sumana Harihareswara committed
25
Hang out on IRC and ask questions on ``#mailman`` or join the `mailing list`_
26
``[email protected]``.
Aurélien Bompard's avatar
Aurélien Bompard committed
27

28
.. _mailing list: https://lists.mailman3.org/mailman3/lists/mailman-users.mailman3.org/
Aurélien Bompard's avatar
Aurélien Bompard committed
29 30


31
Setting up HyperKitty for development
Aurélien Bompard's avatar
Aurélien Bompard committed
32 33
=====================================

34
The recommended way to develop on HyperKitty is to use VirtualEnv. It will
Aurélien Bompard's avatar
Aurélien Bompard committed
35 36 37 38 39 40 41 42 43 44
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::

Aurélien Bompard's avatar
Aurélien Bompard committed
45
    git clone https://gitlab.com/mailman/hyperkitty.git
Aurélien Bompard's avatar
Aurélien Bompard committed
46 47 48
    cd hyperkitty
    python setup.py develop

49
.. include:: _sass.rst
Aurélien Bompard's avatar
Aurélien Bompard committed
50

Aurélien Bompard's avatar
Aurélien Bompard committed
51 52 53
Configuration
=============

Rahul Bothra's avatar
Rahul Bothra committed
54 55
For a development setup, you should create a file
``example_project/settings_local.py`` with at least the following
Aurélien Bompard's avatar
Aurélien Bompard committed
56 57 58 59 60 61
content::

    DEBUG = True
    TEMPLATE_DEBUG = DEBUG
    USE_SSL = False

62
It's also recommended to change the database access paths in the ``DATABASES``
63
and ``HAYSTACK_CONNECTIONS`` variables. Absolute paths are required.
Aurélien Bompard's avatar
Aurélien Bompard committed
64 65

If you ever want to turn the ``DEBUG`` variable to ``False`` (by removing it
Aurélien Bompard's avatar
Aurélien Bompard committed
66 67
from ``settings_local.py``), you'll have to run two additional commands then
and each time you change the static files::
Aurélien Bompard's avatar
Aurélien Bompard committed
68

69 70
    django-admin collectstatic --pythonpath example_project --settings settings
    django-admin compress --pythonpath example_project --settings settings
kpytang's avatar
kpytang committed
71 72 73 74

Normally, to generate compressor content, you'll need to set ``COMPRESS_ENABLED`` to ``TRUE``
and ``COMPRESS_OFFLINE`` to ``TRUE`` in ``settings_local.py``. However, you can force the generation of
compressor content by adding the ``--force`` switch to the ``django-admin compress`` command, which
75
will run the compressor even if the ``COMPRESS`` settings are not ``TRUE``.
Aurélien Bompard's avatar
Aurélien Bompard committed
76 77 78

But for development purposes, it's better to keep ``DEBUG = True``.

79 80 81 82
.. note::
    Your ``django-admin`` command may be called ``django-admin.py`` depending
    on your installation method.

Aurélien Bompard's avatar
Aurélien Bompard committed
83

Aurélien Bompard's avatar
Aurélien Bompard committed
84 85 86 87 88 89 90 91 92 93 94
.. 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::

95
    django-admin runserver --pythonpath example_project --settings settings
Aurélien Bompard's avatar
Aurélien Bompard committed
96 97 98 99 100 101 102 103 104 105 106 107

.. 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::

108
    django-admin test --settings hyperkitty.tests.settings_test hyperkitty
Aurélien Bompard's avatar
Aurélien Bompard committed
109 110 111 112

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``: