README.rst 4.44 KB
Newer Older
1
2
3
=================================
Academic-community Django project
=================================
Philipp Sebastian Sommer's avatar
Philipp Sebastian Sommer committed
4

5
6
`django-academic-community` is a representation of an academic community on the
web using Django.
Philipp Sebastian Sommer's avatar
Philipp Sebastian Sommer committed
7

8
9
Some more documentation is in the "docs" directory, but we are working on
improving this.
Philipp Sebastian Sommer's avatar
Philipp Sebastian Sommer committed
10

11
12
Quick start for development
---------------------------
13
1. You need at least python 3.7, postgres and ``pip`` installed
14
2. Clone this repository::
Philipp Sebastian Sommer's avatar
Philipp Sebastian Sommer committed
15

16
17
       git clone https://gitlab.hzdr.de/hcdc/django/django-academic-community.git
       cd django-academic-communty
Philipp Sebastian Sommer's avatar
Philipp Sebastian Sommer committed
18

19
3. Install the packages (in development mode)::
Philipp Sebastian Sommer's avatar
Philipp Sebastian Sommer committed
20

21
       pip install .[dev]
Philipp Sebastian Sommer's avatar
Philipp Sebastian Sommer committed
22

23
24
25
26
27
5. By default, we assume that there exists a ``django_academic_community``
   database that is writeable for a user name ``django_academic_user`` with
   password ``admin``. But you can change this with environment variables (see
   `settings.py <clm_tools_test_site/settings.py>`__).
   Run::
28
29
30

       python manage.py migrate

31
   to setup the database.
32

33
34
35
36
6. Create the initial revisions (necessary for django-reversion_)::

       python manage.py createinitialrevisions

37
7. Create a superuser via::
38
39
40

       python manage.py createsuperuser

41
8.  Run the local development server via::
42
43
44

       python manage.py runserver

45
46
    Open the topic browser at http://127.0.0.1:8000/topics, and the admin site
    at http://127.0.0.1:8000/admin
47
48


49
50
51
.. _django-reversion: https://django-reversion.readthedocs.io


52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
Building the docs
-----------------
There is some static files generated via sphinx, together with an API
documentation. The source code for this documentation is in the `docs <docs>`__
folder. If you installed this package with the above ``pip install`` command,
you already have everything you need. The only thing that you should have
installed already is ``graphviz`` (e.g. via ``conda install graphviz``).

Navigate to the `docs <docs>`__ folder and run ``make html`` (on linux) or
``make.bat html`` on windows and open the file at
``docs/_build/html/index.html`` in your browser.

Some of the documentation in this content is also available through the admin
docs. When you run the server (``python manage.py runserver``), navigate to the
docs under http://127.0.0.1:8000/admin/docs.

Note that there is still a lot to work on for the documentation, so in case you
are missing something, please do not hesitate to ask.

Running the tests
-----------------
Just run ``tox`` (you installed it with ``pip install .[dev]``).
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
Note that you will need a running postgres server and a user with the rights
to create a new postgres database.

Contributing
------------

   We are working on a more detailed contributing guide, but here is the
   short version:

When you want to contribute to the code, please do clone the source code
repository and install it with the ``[dev]`` extra, i.e.

.. code:: bash

   git clone https://gitlab.hzdr.de/hcdc/django/clm-community/django-academic-community/
   cd django-academic-community
   pip install -e .[dev]

We use automated formatters (see their config in ``pyproject.toml`` and
``setup.cfg``), namely

-  `Black <https://black.readthedocs.io/en/stable/>`__ for standardized
   code formatting
-  `blackdoc <https://blackdoc.readthedocs.io/en/stable/>`__ for
   standardized code formatting in documentation
-  `Flake8 <http://flake8.pycqa.org/en/latest/>`__ for general code
   quality
-  `isort <https://github.com/PyCQA/isort>`__ for standardized order in
   imports.
-  `mypy <http://mypy-lang.org/>`__ for static type checking on `type
   hints <https://docs.python.org/3/library/typing.html>`__

We highly recommend that you setup `pre-commit
hooks <https://pre-commit.com/>`__ to automatically run all the above
tools every time you make a git commit. This can be done by running

::

   pre-commit install

from the root of the repository. You can skip the pre-commit checks with
``git commit --no-verify`` but note that the CI will fail if it
encounters any formatting errors.

You can also run the pre-commit step manually by invoking

::

   pre-commit run --all-files

124
125
126
127
128
129
130
131
132
133
134
135
136
137


Copyright
---------
Copyright © 2021 Helmholtz-Zentrum Hereon, 2020-2021 Helmholtz-Zentrum Geesthacht

Licensed under the EUPL-1.2-or-later

This program 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 EUPL-1.2 license for more details.

You should have received a copy of the EUPL-1.2 license along with this
program. If not, see https://www.eupl.eu/.