Skip to content

Commit 8edd878

Browse files
dennissiemensmadennissiemensma
committed
Documentation: Development environment #442 
1 parent b6c1395 commit 8edd878

File tree

2 files changed

+131
-8
lines changed

2 files changed

+131
-8
lines changed

‎docs/contributing.rst

+4-4
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,9 @@ It doesn't matter whether you run into problems or just want to get in touch, ju
1313
`Please create an issue on Github <https://github.com/dennissiemensma/dsmr-reader/issues/new>`_ to get in contact.
1414

1515

16-
Pull requests
17-
-------------
16+
Developing and creating pull requests
17+
-------------------------------------
1818
Pull requests are appreciated, but please note that you should discuss any changes with a Github ticket first.
19-
It would be a shame if you'd put any effort in something that won't get merged after all.
19+
It would be a shame if you'd put any effort in something that won't get merged after all.
2020

21-
Also, please do not create pull requests for the ``master`` branch, but always point it to ``development``.
21+
For more information about how to develop, :doc:`see the page dedicated to this topic<development>`.

‎docs/development.rst

+127-4
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,22 @@
1-
Development
2-
===========
1+
Developing with DSMR-reader
2+
===========================
33

44

55
.. contents::
66
:depth: 2
77

8+
.. note::
9+
10+
In this document there are many references to::
11+
12+
source ~/.virtualenvs/dsmrreader/bin/activate
13+
14+
You will only have to execute it once per terminal session, to make sure you are working in the designated virtual env for DSMR-reader.
15+
816

917
Setting up a development environment in Ubuntu 18.04
1018
----------------------------------------------------
19+
1120
System packages::
1221
1322
sudo apt-get install -y postgresql postgresql-server-dev-all git python3 python3-pip python3-virtualenv virtualenvwrapper libmysqlclient-dev mariadb-server poedit
@@ -28,7 +37,7 @@ Copy development config::
2837

2938
cp dsmrreader/provisioning/django/development.py dsmrreader/settings.py
3039

31-
Try a check, output should be something like: ``System check identified no issues (0 silenced).``::
40+
Try a check, output should be something like ``System check identified no issues (0 silenced).``::
3241
3342
./manage.py check
3443

@@ -51,7 +60,121 @@ Set up MySQL (or MariaDB) test database::
5160
GRANT ALL PRIVILEGES ON *.* TO 'dsmrreader'@'localhost' IDENTIFIED BY 'dsmrreader';
5261
FLUSH PRIVILEGES;
5362

54-
Now test whether tests run well with all three database backends (this may take a while)::
63+
Now check whether tests run well with all three database backends (this may take a while)::
5564

5665
./tools/test-all.sh
5766

67+
68+
Initial data to develop with
69+
----------------------------
70+
71+
To be honest, the best initial/fixture data is simply a backup of your own system in production.
72+
73+
Just import it as you should on your RaspberryPi. Copy a database backup to ``/var/lib/postgresql/`` on your PC and import it::
74+
75+
# Create empty database if it does not exist yet.
76+
sudo sudo -u postgres createdb -O dsmrreader dsmrreader
77+
78+
# For .SQL
79+
sudo sudo -u postgres psql dsmrreader -f <PATH-TO-POSTGRESQL-BACKUP.sql>
80+
81+
# For .SQL.GZ
82+
zcat <PATH-TO-POSTGRESQL-BACKUP.sql.gz> | sudo sudo -u postgres psql dsmrreader
83+
84+
.. warning::
85+
86+
Please note that you should not run any (backend) processes in your DSMR-reader development environment, until you've unlinked all external services.
87+
88+
After importing the backup of your production system, simply run::
89+
90+
source ~/.virtualenvs/dsmrreader/bin/activate
91+
./manage.py development_reset
92+
93+
This will remove all API keys and other links to externals systems, as well as reset the admin user credentials to ``admin / admin`` (user / password).
94+
95+
96+
Fake datalogger
97+
---------------
98+
99+
There is a builtin command that can somewhat fake a datalogger::
100+
101+
source ~/.virtualenvs/dsmrreader/bin/activate
102+
./manage.py dsmr_fake_datasource --ack-to-mess-up-my-data --with-gas --with-electricity-returned
103+
104+
It will generate random data every second in a certain pattern and should be fine for basic testing.
105+
106+
Please note that it only inserts unprocessed readings, so you'll still have to run the ``./manage.py dsmr_backend --run-once`` command to have the readings processed.
107+
108+
109+
Running DSMR-reader locally
110+
---------------------------
111+
112+
You can run the Django development server with::
113+
114+
source ~/.virtualenvs/dsmrreader/bin/activate
115+
./manage.py runserver
116+
117+
The application will be accessible on: ``http://localhost:8000/``.
118+
Any code changes you make will let the application reload automatically.
119+
120+
121+
Tests
122+
-----
123+
124+
The easiest way to run tests is to use the in-memory tests::
125+
126+
source ~/.virtualenvs/dsmrreader/bin/activate
127+
./tools/quick-test.sh
128+
129+
To test a single apps within DSMR-reader, just append it::
130+
131+
source ~/.virtualenvs/dsmrreader/bin/activate
132+
./tools/quick-test.sh dsmr_frontend
133+
134+
To test all database backends, run::
135+
136+
source ~/.virtualenvs/dsmrreader/bin/activate
137+
./tools/test-all.sh
138+
139+
Translations
140+
------------
141+
142+
You can find the translations (.PO files) for the main application in ``dsmrreader/locales/``.
143+
To regenerate them, just execute the ``./tools/quick-test.sh`` script, as one of the tests checks translations.
144+
145+
146+
Editing documentation
147+
---------------------
148+
149+
The documentation is part of the repository and can be generated (automatically) with Sphinx::
150+
151+
source ~/.virtualenvs/dsmrreader/bin/activate
152+
cd docs/
153+
sphinx-autobuild . _build/html -p 10000
154+
155+
You can now view the documentation in your browser by accessing: ``http://127.0.0.1:10000``.
156+
Any changes you make will be reflected instantly in the browser, as Sphinx continuously checks for changed files.
157+
158+
159+
Translating documentation
160+
-------------------------
161+
162+
Translations are done using gettext and .PO files. Regenerate the .PO files with::
163+
164+
source ~/.virtualenvs/dsmrreader/bin/activate
165+
cd docs/
166+
make gettext && sphinx-intl update -p _build/locale -l nl
167+
168+
The .PO files in ``docs/locale`` shoud be regenerated now. You can use ``poedit`` to view and translate the files.
169+
170+
After editing the .PO files, you can check the result by building the Dutch translations locally::
171+
172+
make -e SPHINXOPTS="-D language='nl'" html
173+
174+
Now view the generated HTML in your browser by opening: ``docs/_build/html/index.html``
175+
176+
177+
Pull requests
178+
-------------
179+
180+
Please make sure to always point any pull requests to the ``development`` branch of DSMR-reader, as the ``master`` branch will only be affected by release merges.

0 commit comments

Comments
 (0)