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
``mailman-users@mailman3.org``.
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
    cd hyperkitty
47
    pip install -e '.[dev]'
Aurélien Bompard's avatar
Aurélien Bompard committed
48

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