diff --git a/.gitignore b/.gitignore index f22a53bd6..2d0cfa530 100644 --- a/.gitignore +++ b/.gitignore @@ -54,3 +54,4 @@ node_modules/ # virtual environments .env +docs/_build diff --git a/README.rst b/README.rst index c890105b5..5e819366c 100644 --- a/README.rst +++ b/README.rst @@ -17,56 +17,3 @@ Feder ============================== Mechanizm do automatycznego wysyłania wniosków o informację do dużej liczby podmiotów, automatycznego przyjmowania odpowiedzi, udostępnienia otrzymanych odpowiedzi do analizy pod wybranym kątem przez masowo angażowanych do tego zadania obywateli oraz upubliczniania zweryfikowanych odpowiedzi i zestawień uzyskanych danych. - - -LICENSE: BSD - -Getting up and running ----------------------- - -The steps below will get you up and running with a local development environment. We assume you have the following installed -First make sure to install all requires OS-level libraries and application (dependencies):: - - $ sudo apt-get install python2.7 mariadb-server git libmariadbclient-dev virtualenv python-dev libffi-dev libssl-dev libjpeg-dev libpng12-dev libxml2-dev libxslt1-dev build-essential libjpeg62 - -Next to create and activate a virtualenv_:: - - $ virtualenv env - $ source env/bin/activate - - .. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/ - -Next to open a terminal at the project root and install the requirements for local development:: - - $ pip install pip wheel -U - $ pip install -r requirements/local.txt - -Next to create MySQL database:: - - # if you are using Ubuntu 14.04, you may need to find a workaround for the following two commands - $ sudo systemctl start mariadb - $ sudo systemctl enable mariadb - - $ mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql - - $ echo "CREATE DATABASE feder CHARACTER SET utf8 COLLATE utf8_polish_ci;" | mysql -u root - $ echo "CREATE USER 'user'@'localhost' IDENTIFIED BY 'pass';" | mysql -u root - $ echo "GRANT ALL PRIVILEGES ON feder . * TO 'user'@'localhost'; FLUSH PRIVILEGES;" | mysql -u root - -Next to set up enviroment variables:: - - $ export DJANGO_SETTINGS_MODULE="config.local" - $ export DATABASE_URL="mysql://user:pass@localhost/feder" - -Next to push migrations into database:: - - $ python poradnia/manage.py migrate - -You can now run the usual Django ``runserver`` command:: - - $ python poradnia/manage.py runserver - -To run tests use:: - - $ pip install -r requirements/test.txt - $ python manage.py test $@ -v2 diff --git a/docs/Makefile b/docs/Makefile index 33fa16762..ed1243fe1 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -77,17 +77,17 @@ qthelp: @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/feder.qhcp" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/watchdog_kj_kultura.qhcp" @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/feder.qhc" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/watchdog_kj_kultura.qhc" devhelp: $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp @echo @echo "Build finished." @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/feder" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/feder" + @echo "# mkdir -p $$HOME/.local/share/devhelp/watchdog_kj_kultura" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/watchdog_kj_kultura" @echo "# devhelp" epub: diff --git a/docs/_images/tasks_model.svg b/docs/_images/tasks_model.svg new file mode 100644 index 000000000..5ab46fc6c --- /dev/null +++ b/docs/_images/tasks_model.svg @@ -0,0 +1,355 @@ + + + + + + +model_graph + +cluster_feder_questionaries + +           +          feder.questionaries           +           + +cluster_feder_tasks + +           +          feder.tasks           +           + + +model_utils_models_TimeStampedModel + + +       +      TimeStampedModel       +       +created +       +       +AutoCreatedField +       +       +modified +       +       +AutoLastModifiedField +       + + +feder_questionaries_models_Questionary + + +       +      Questionary +< +TimeStampedModel +>       +       +id +       +       +AutoField +       +       +monitoring +       +       +ForeignKey (id) +       +       +created +       +       +AutoCreatedField +       +       +lock +       +       +BooleanField +       +       +modified +       +       +AutoLastModifiedField +       +       +title +       +       +CharField +       + + +feder_questionaries_models_Questionary->model_utils_models_TimeStampedModel + + +abstract +inheritance + + +feder_monitorings_models_Monitoring + + +   +Monitoring +   + + +feder_questionaries_models_Questionary->feder_monitorings_models_Monitoring + + +monitoring (questionary) + + +feder_questionaries_models_Question + + +       +      Question       +       +id +       +       +AutoField +       +       +questionary +       +       +ForeignKey (id) +       +       +definition +       +       +JSONField +       +       +genre +       +       +CharField +       +       +position +       +       +SmallIntegerField +       + + +feder_questionaries_models_Question->feder_questionaries_models_Questionary + + +questionary (question) + + +feder_tasks_models_Task + + +       +      Task +< +TimeStampedModel +>       +       +id +       +       +AutoField +       +       +case +       +       +ForeignKey (id) +       +       +questionary +       +       +ForeignKey (id) +       +       +created +       +       +AutoCreatedField +       +       +modified +       +       +AutoLastModifiedField +       +       +name +       +       +CharField +       +       +survey_done +       +       +SmallIntegerField +       +       +survey_required +       +       +SmallIntegerField +       + + +feder_tasks_models_Task->model_utils_models_TimeStampedModel + + +abstract +inheritance + + +feder_tasks_models_Task->feder_questionaries_models_Questionary + + +questionary (task) + + +feder_cases_models_Case + + +   +Case +   + + +feder_tasks_models_Task->feder_cases_models_Case + + +case (task) + + +feder_tasks_models_Survey + + +       +      Survey +< +TimeStampedModel +>       +       +id +       +       +AutoField +       +       +task +       +       +ForeignKey (id) +       +       +user +       +       +ForeignKey (id) +       +       +created +       +       +AutoCreatedField +       +       +credibility +       +       +PositiveIntegerField +       +       +modified +       +       +AutoLastModifiedField +       + + +feder_tasks_models_Survey->model_utils_models_TimeStampedModel + + +abstract +inheritance + + +feder_tasks_models_Survey->feder_tasks_models_Task + + +task (survey) + + +feder_users_models_User + + +   +User +   + + +feder_tasks_models_Survey->feder_users_models_User + + +user (survey) + + +feder_tasks_models_Answer + + +       +      Answer       +       +id +       +       +AutoField +       +       +question +       +       +ForeignKey (id) +       +       +survey +       +       +ForeignKey (id) +       +       +content +       +       +JSONField +       + + +feder_tasks_models_Answer->feder_questionaries_models_Question + + +question (answer) + + +feder_tasks_models_Answer->feder_tasks_models_Survey + + +survey (answer) + + + diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/_static/geocoding.webm b/docs/_static/geocoding.webm new file mode 100644 index 000000000..182e74ef8 Binary files /dev/null and b/docs/_static/geocoding.webm differ diff --git a/docs/administration/deploy.rst b/docs/administration/deploy.rst new file mode 100644 index 000000000..4026c6e64 --- /dev/null +++ b/docs/administration/deploy.rst @@ -0,0 +1,10 @@ +.. _deploy: + +********* +Wdrożenie +********* + +Został opublikowany playbook Ansible, który zapewnia wdrożenie aplikacji. + + .. todo:: + Publikacja Playbooka diff --git a/docs/administration/fixtures.rst b/docs/administration/fixtures.rst new file mode 100644 index 000000000..ecc98e284 --- /dev/null +++ b/docs/administration/fixtures.rst @@ -0,0 +1,7 @@ +.. _fixtures: + +************ +Dane testowe +************ + +W celu szybkiego rozruchu aplikacji możliwe jest wygenerowanie lub wczytanie pewnych danych początkowych. Szczegółowe instrukcje zostały przedstawione w modułach właściwych modułów. diff --git a/docs/administration/install.rst b/docs/administration/install.rst new file mode 100644 index 000000000..40fbd33ba --- /dev/null +++ b/docs/administration/install.rst @@ -0,0 +1,52 @@ +.. _installation: + +****************** +Instalacja +****************** + +The steps below will get you up and running with a local development environment. We assume you have the following installed +First make sure to install all requires OS-level libraries and application (dependencies):: + + $ sudo apt-get install python2.7 mariadb-server git libmariadbclient-dev virtualenv python-dev libffi-dev libssl-dev libjpeg-dev libpng12-dev libxml2-dev libxslt1-dev build-essential libjpeg62 + +Next to create and activate a virtualenv_:: + + $ virtualenv env + $ source env/bin/activate + + .. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/ + +Next to open a terminal at the project root and install the requirements for local development:: + + $ pip install pip wheel -U + $ pip install -r requirements/local.txt + +Next to create MySQL database:: + + # if you are using Ubuntu 14.04, you may need to find a workaround for the following two commands + $ sudo systemctl start mariadb + $ sudo systemctl enable mariadb + + $ mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql + + $ echo "CREATE DATABASE feder CHARACTER SET utf8 COLLATE utf8_polish_ci;" | mysql -u root + $ echo "CREATE USER 'user'@'localhost' IDENTIFIED BY 'pass';" | mysql -u root + $ echo "GRANT ALL PRIVILEGES ON feder . * TO 'user'@'localhost'; FLUSH PRIVILEGES;" | mysql -u root + +Next to set up enviroment variables:: + + $ export DJANGO_SETTINGS_MODULE="config.local" + $ export DATABASE_URL="mysql://user:pass@localhost/feder" + +Next to push migrations into database:: + + $ python poradnia/manage.py migrate + +You can now run the usual Django ``runserver`` command:: + + $ python poradnia/manage.py runserver + +To run tests use:: + + $ pip install -r requirements/test.txt + $ python manage.py test $@ -v2 diff --git a/docs/conf.py b/docs/conf.py index 9e1d1f781..a1b8bba4d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -11,9 +11,23 @@ # All configuration values have a default; values that are commented out # serve to show the default. +from __future__ import unicode_literals + +import inspect import os import sys +import django +from django.core.urlresolvers import get_resolver +from django.utils.encoding import force_text +from django.utils.html import strip_tags + +sys.path.append(os.path.abspath('..')) +os.environ['DJANGO_SETTINGS_MODULE'] = 'config.settings.local' +os.environ['DATABASE_URL'] = 'mysql://' + +django.setup() + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. @@ -26,7 +40,23 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [] +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.viewcode', + 'sphinx.ext.intersphinx', + 'sphinx.ext.coverage', + 'sphinx.ext.napoleon', + 'sphinx.ext.todo', + 'sphinxcontrib.programoutput' +] + +intersphinx_mapping = { + 'python': ('https://python.readthedocs.io/en/v2.7.2/', None), + 'django': ('https://docs.djangoproject.com/en/dev/', + 'http://docs.djangoproject.com/en/dev/_objects/'), + 'sphinx': ('https://sphinx.readthedocs.io/en/latest/', None), + 'grappelli': ('https://django-grappelli.readthedocs.io/en/latest/', None), +} # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -37,12 +67,13 @@ # The encoding of source files. # source_encoding = 'utf-8-sig' + # The master toctree document. master_doc = 'index' # General information about the project. -project = u'feder' -copyright = u"2015, Adam Dobrawy" +project = 'feder' +copyright = """2016, Adam Dobrawy""" # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -51,7 +82,7 @@ # The short X.Y version. version = '0.1' # The full version, including alpha/beta/rc tags. -release = '0.1' +release = version # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -92,7 +123,14 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +try: + import sphinx_rtd_theme + + html_theme = "sphinx_rtd_theme" + + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +except ImportError: + html_theme = 'default' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -186,8 +224,8 @@ latex_documents = [ ('index', 'feder.tex', - u'feder Documentation', - u"Adam Dobrawy", 'manual'), + 'feder Documentation', + """Adam Dobrawy""", 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -216,13 +254,14 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'feder', u'feder Documentation', - [u"Adam Dobrawy"], 1) + ('index', 'feder', 'feder Documentation', + ["""Adam Dobrawy"""], 1) ] # If true, show URL addresses after external links. # man_show_urls = False +todo_include_todos = True # -- Options for Texinfo output ------------------------------------------------ @@ -230,9 +269,9 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - ('index', 'feder', u'feder Documentation', - u"Adam Dobrawy", 'feder', - 'Mechanizm do automatycznego wysyłania wniosków o informację do dużej liczby podmiotów, automatycznego przyjmowania odpowiedzi, udostępnienia otrzymanych odpowiedzi do analizy pod wybranym kątem przez masowo angażowanych do tego zadania obywateli oraz upubliczniania zweryfikowanych odpowiedzi i zestawień uzyskanych danych.', 'Miscellaneous'), + ('index', 'feder', 'feder Documentation', + """Adam Dobrawy""", 'feder', + """Obywatelskie fedrowanie danych.""", 'Miscellaneous'), ] # Documents to append as an appendix to all manuals. @@ -243,3 +282,72 @@ # How to display URL addresses: 'footnote', 'no', or 'inline'. # texinfo_show_urls = 'footnote' + + +def process_django_model(app, what, name, obj, options, lines): + # This causes import errors if left outside the function + from django.db import models + + # Only look at objects that inherit from Django's base model class + if inspect.isclass(obj) and issubclass(obj, models.Model): + # Grab the field list from the meta class + fields = obj._meta.fields + + for field in fields: + # Decode and strip any html out of the field's help text + help_text = strip_tags(force_text(field.help_text)) + + # Decode and capitalize the verbose name, for use if there isn't + # any help text + verbose_name = force_text(field.verbose_name).capitalize() + + if help_text: + # Add the model field to the end of the docstring as a param + # using the help text as the description + lines.append(':param %s: %s' % (field.attname, help_text)) + else: + # Add the model field to the end of the docstring as a param + # using the verbose name as the description + lines.append(':param %s: %s' % (field.attname, verbose_name)) + + # Add the field's type to the docstring + if isinstance(field, (models.ForeignKey, models.OneToOneField, models.ManyToManyField)): + lines.append(':type %s: %s to :class:`%s.%s`' % (field.attname, + type(field).__name__, + field.rel.to.__module__, + field.rel.to.__name__)) + else: + lines.append(':type %s: %s' % (field.attname, type(field).__name__)) + # Return the extended docstring + return lines + + +def process_django_view(app, what, name, obj, options, lines): + res = get_resolver() + flat_patterns = [] + + def walker(flat_patterns, urlpatterns, namespace=None): + for pattern in urlpatterns: + if hasattr(pattern, 'url_patterns'): + walker(flat_patterns, pattern.url_patterns, pattern.namespace) + else: + urlname = '%s:%s' % (namespace, pattern.name) if namespace else pattern.name + flat_patterns.append([urlname, pattern.callback]) + walker(flat_patterns, res.url_patterns) + for urlname, callback in flat_patterns: + if (hasattr(callback, 'view_class') and callback.view_class == obj) or callback == obj: + lines.append(":param url_name: ``%s``\n" % urlname) + return lines + + +def process_django_form(app, what, name, obj, options, lines): + from django import forms + if inspect.isclass(obj) and issubclass(obj, (forms.Form, forms.ModelForm)): + for fieldname, field in obj.base_fields.items(): + lines.append(u':param %s: %s' % (fieldname, field.label)) + + +def setup(app): + app.connect('autodoc-process-docstring', process_django_model) + app.connect('autodoc-process-docstring', process_django_view) + app.connect('autodoc-process-docstring', process_django_form) diff --git a/docs/deploy.rst b/docs/deploy.rst deleted file mode 100644 index 1e642c798..000000000 --- a/docs/deploy.rst +++ /dev/null @@ -1,4 +0,0 @@ -Deploy -======== - -This is where you describe how the project is deployed in production. diff --git a/docs/development/development.rst b/docs/development/development.rst new file mode 100644 index 000000000..f8bf6def5 --- /dev/null +++ b/docs/development/development.rst @@ -0,0 +1,62 @@ +.. _development: + +****************** +Rozwój +****************** + +W tym dokumencie opisujemy opis procesu rozwoju aplkacji. Ma on postać FAQ, aby utrzymywać dokument prostym. + + +Jak zgłosić usterkę? +-------------------- + +Po prostu przejdź na https://github.com/watchdogpolska/feder/issues i utworz zgłoszenie. + + +Jak diagnozować funkcjonowanie poczty elektronicznej? +----------------------------------------------------- + +W środowisku deweloperskim wiadomości e-mail są domyślnie wypisywane na konsole w oknie serwera WWW. Jeżeli chcesz zweryfikować np. formatowanie wiadomości zaleca się wykorzystanie `maildump`_, który możliwy jest do zainstalowania i uruchomienia poprzez:: + + $ pip install maildump + $ maildump + +Następnie należy ponownie uruchomić serwer WWW w następujący sposób ``EMAIL_URL=smtp://localhost:1025/ python manage.py runserver``. Wiadomości będą dostępne przez interfejs WWW +pod adresem ``http://localhost:1080``. + +.. _`maildump`: https://github.com/ThiefMaster/maildump + +Jak uruchomić automatyczne testy? +--------------------------------- + +Do prawidłowego uruchomienia automatycznych testów bezwzględnie wymagane jest zainstalowanie wszystkich deweloperskich pakietów. Można to osiągnąc poprzez:: + + $ pip install -r requirements/dev.txt; + +Następnie należy wywołać:: + + $ python manage.py test + +Warto wyróznić kilka przełączników, które mogą zapewnić sprawniejsze wykorzystanie testów: + +- ``-v2`` oznacza, że będą na bieżąco wypisywane nazwy wszystkich testów wraz z ich rezultatem, +- ``--keepdb`` oznacza, że struktura bazy danych nie zostanie skasowana po wykonaniu testów, co pozwala oszczędzić jej tworzenie każdorazowo, co jednak uniemożliwi wykrycie testów np. w migracjach, +- ``--parallel 4`` oznacza, że testy będa wykonywane równolegle, a wcześniej zostaną utworzone 4 identyczne struktury bazy danych. + +.. warning:: Warto zaznaczyć, że zrównoleglenie testów nie oznacza, że będą one wykonywane szybciej niż proces utworzenia dodatkowych baz danych może się wydłużyć o więcej niż sam proces wykonywania testów. + + +Jak wygenerować dokumentacje? +----------------------------- + +Do prawidłowego uruchomienia automatycznych testów bezwzględnie wymagane jest zainstalowanie wszystkich deweloperskich pakietów. Można to osiągnąc poprzez:: + + $ pip install -r requirements/dev.txt; + +Nastepnie należy przejść do katalogu ``docs`` i wywołać:: + + $ make html + +Warto zaznaczyć, że aktualna dokumentacja jest budowana automatycznie i publikowana na `Read the Docs`_. + +.. _`Read the Docs`: http://watchdog-kj-kultura.readthedocs.io/ diff --git a/docs/docker_ec2.rst b/docs/docker_ec2.rst deleted file mode 100644 index 6314118ec..000000000 --- a/docs/docker_ec2.rst +++ /dev/null @@ -1,186 +0,0 @@ -Developing with Docker -====================== - -You can develop your application in a `Docker`_ container for simpler deployment onto bare Linux machines later. This instruction assumes an `Amazon Web Services`_ EC2 instance, but it should work on any machine with Docker > 1.3 and `Docker compose`_ installed. - -.. _Docker: https://www.docker.com/ -.. _Amazon Web Services: http://aws.amazon.com/ -.. _Docker compose: https://docs.docker.com/compose/ - -Setting up -^^^^^^^^^^ - -Docker encourages running one container for each process. This might mean one container for your web server, one for Django application and a third for your database. Once you're happy composing containers in this way you can easily add more, such as a `Redis`_ cache. - -.. _Redis: http://redis.io/ - -The Docker compose tool (previously known as `fig`_) makes linking these containers easy. An example set up for your cookiecutter-django project might look like this: - -.. _fig: http://www.fig.sh/ - -:: - - webapp/ # Your cookiecutter project would be in here - Dockerfile - ... - database/ - Dockerfile - ... - webserver/ - Dockerfile - ... - docker-compose.yml - -Each component of your application would get its own `Dockerfile`_. The rest of this example assumes you are using the `base postgres image`_ for your database. Your database settings in `config/common.py` might then look something like: - -.. _Dockerfile: https://docs.docker.com/reference/builder/ -.. _base postgres image: https://registry.hub.docker.com/_/postgres/ - -.. code-block:: python - - DATABASES = { - 'default': { - 'ENGINE': 'django.db.backends.postgresql_psycopg2', - 'NAME': 'postgres', - 'USER': 'postgres', - 'HOST': 'database', - 'PORT': 5432, - } - } - -The `Docker compose documentation`_ explains in detail what you can accomplish in the `docker-compose.yml` file, but an example configuration might look like this: - -.. _Docker compose documentation: https://docs.docker.com/compose/#compose-documentation - -.. code-block:: yaml - - database: - build: database - webapp: - build: webapp: - command: /usr/bin/python3.4 manage.py runserver 0.0.0.0:8000 # dev setting - # command: gunicorn -b 0.0.0.0:8000 wsgi:application # production setting - volumes: - - webapp/your_project_name:/path/to/container/workdir/ - links: - - database - webserver: - build: webserver - ports: - - "80:80" - - "443:443" - links: - - webapp - -We'll ignore the webserver for now (you'll want to comment that part out while we do). A working Dockerfile to run your cookiecutter application might look like this: - -:: - - FROM ubuntu:14.04 - ENV REFRESHED_AT 2015-01-13 - - # update packages and prepare to build software - RUN ["apt-get", "update"] - RUN ["apt-get", "-y", "install", "build-essential", "vim", "git", "curl"] - RUN ["locale-gen", "en_GB.UTF-8"] - - # install latest python - RUN ["apt-get", "-y", "build-dep", "python3-dev", "python3-imaging"] - RUN ["apt-get", "-y", "install", "python3-dev", "python3-imaging", "python3-pip"] - - # prepare postgreSQL support - RUN ["apt-get", "-y", "build-dep", "python3-psycopg2"] - - # move into our working directory - # ADD must be after chown see http://stackoverflow.com/a/26145444/1281947 - RUN ["groupadd", "python"] - RUN ["useradd", "python", "-s", "/bin/bash", "-m", "-g", "python", "-G", "python"] - ENV HOME /home/python - WORKDIR /home/python - RUN ["chown", "-R", "python:python", "/home/python"] - ADD ./ /home/python - - # manage requirements - ENV REQUIREMENTS_REFRESHED_AT 2015-02-25 - RUN ["pip3", "install", "-r", "requirements.txt"] - - # uncomment the line below to use container as a non-root user - USER python:python - -Running `sudo docker-compose build` will follow the instructions in your `docker-compose.yml` file and build the database container, then your webapp, before mounting your cookiecutter project files as a volume in the webapp container and linking to the database. Our example yaml file runs in development mode but changing it to production mode is as simple as commenting out the line using `runserver` and uncommenting the line using `gunicorn`. - -Both are set to run on port `0.0.0.0:8000`, which is where the Docker daemon will discover it. You can now run `sudo docker-compose up` and browse to `localhost:8000` to see your application running. - -Deployment -^^^^^^^^^^ - -You'll need a webserver container for deployment. An example setup for `Nginx`_ might look like this: - -.. _Nginx: http://wiki.nginx.org/Main - -:: - - FROM ubuntu:14.04 - ENV REFRESHED_AT 2015-02-11 - - # get the nginx package and set it up - RUN ["apt-get", "update"] - RUN ["apt-get", "-y", "install", "nginx"] - - # forward request and error logs to docker log collector - RUN ln -sf /dev/stdout /var/log/nginx/access.log - RUN ln -sf /dev/stderr /var/log/nginx/error.log - VOLUME ["/var/cache/nginx"] - EXPOSE 80 443 - - # load nginx conf - ADD ./site.conf /etc/nginx/sites-available/your_cookiecutter_project - RUN ["ln", "-s", "/etc/nginx/sites-available/your_cookiecutter_project", "/etc/nginx/sites-enabled/your_cookiecutter_project"] - RUN ["rm", "-rf", "/etc/nginx/sites-available/default"] - - #start the server - CMD ["nginx", "-g", "daemon off;"] - -That Dockerfile assumes you have an Nginx conf file named `site.conf` in the same directory as the webserver Dockerfile. A very basic example, which forwards traffic onto the development server or gunicorn for processing, would look like this: - -:: - - # see http://serverfault.com/questions/577370/how-can-i-use-environment-variables-in-nginx-conf#comment730384_577370 - upstream localhost { - server webapp_1:8000; - } - server { - location / { - proxy_pass http://localhost; - } - } - -Running `sudo docker-compose build webserver` will build your server container. Running `sudo docker-compose up` will now expose your application directly on `localhost` (no need to specify the port number). - -Building and running your app on EC2 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -All you now need to do to run your app in production is: - -* Create an empty EC2 Linux instance (any Linux machine should do). - -* Install your preferred source control solution, Docker and Docker compose on the news instance. - -* Pull in your code from source control. The root directory should be the one with your `docker-compose.yml` file in it. - -* Run `sudo docker-compose build` and `sudo docker-compose up`. - -* Assign an `Elastic IP address`_ to your new machine. - -.. _Elastic IP address: https://aws.amazon.com/articles/1346 - -* Point your domain name to the elastic IP. - -**Be careful with Elastic IPs** because, on the AWS free tier, if you assign one and then stop the machine you will incur charges while the machine is down (presumably because you're preventing them allocating the IP to someone else). - -Security advisory -^^^^^^^^^^^^^^^^^ - -The setup described in this instruction will get you up-and-running but it hasn't been audited for security. If you are running your own setup like this it is always advisable to, at a minimum, examine your application with a tool like `OWASP ZAP`_ to see what security holes you might be leaving open. - -.. _OWASP ZAP: https://www.owasp.org/index.php/OWASP_Zed_Attack_Proxy_Project diff --git a/docs/index.rst b/docs/index.rst index b2885abcb..eaede1e18 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,21 +1,44 @@ -.. feder documentation master file, created by +.. watchdog-kj-kultura documentation master file, created by sphinx-quickstart. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to feder's documentation! -==================================================================== +Witam w dokumentacji Obywatelskiego Fedrowania Danych! +====================================================== -Contents: +.. _toc_introduction: .. toctree:: :maxdepth: 2 + :caption: Wprowadzenie - install - deploy - docker_ec2 - tests + introduction/readme + introduction/architecture + introduction/admin_panel +.. _toc_administration: + +.. toctree:: + :caption: Administracja + + administration/install + administration/deploy + administration/fixtures + +.. _toc_modules: + +.. toctree:: + :caption: Moduły + :glob: + + modules/* + +.. _toc_development: + +.. toctree:: + :caption: Rozwój + + development/development Indices and tables diff --git a/docs/install.rst b/docs/install.rst deleted file mode 100644 index 1bc03335d..000000000 --- a/docs/install.rst +++ /dev/null @@ -1,4 +0,0 @@ -Install -========= - -This is where you write how to get a new laptop to run this project. diff --git a/docs/introduction/admin_panel.rst b/docs/introduction/admin_panel.rst new file mode 100644 index 000000000..6d2d46674 --- /dev/null +++ b/docs/introduction/admin_panel.rst @@ -0,0 +1,8 @@ +.. _admin_panel: + +********************* +Panel administracyjny +********************* + +Dostęp do panelu administracyjnego, na których odbywać się będzie zarządzanie wszystkimi zasobami portalu jest tylko możliwy po autoryzacji i wyłącznie dla konkretnych osób. Tworzenie kont administracyjnych jest możliwe wyłącznie z poziomu administracyjnego, to znaczy, że konto administracyjne może założyć osoba zalogowana do panelu. Oprogramowanie portalu zapewnia rejestrowaną i skuteczną kontrolę dostępu. + diff --git a/docs/introduction/architecture.rst b/docs/introduction/architecture.rst new file mode 100644 index 000000000..bc590c86b --- /dev/null +++ b/docs/introduction/architecture.rst @@ -0,0 +1,16 @@ +************ +Architektura +************ + +Aplikacja została wykonana zaimplentowana w języku Python 2.7 z wsparciem frameworku `Django 1.10`_. Została zaprojektowania do wykorzystania bazy danych `MariaDB`_. + +.. _`Django 1.10`: https://docs.djangoproject.com/en/1.10/ +.. _`MariaDB`: https://mariadb.com/ + +Zestawienie bibliotek Python wykorzystanych w projekcie: + +.. literalinclude:: ../requirements/base.txt + +Ponadto podczas pracy deweloperskiej są wykorzystane następujące biblioteki: + +.. literalinclude:: ../requirements/dev.txt diff --git a/docs/introduction/readme.rst b/docs/introduction/readme.rst new file mode 100644 index 000000000..b0620094e --- /dev/null +++ b/docs/introduction/readme.rst @@ -0,0 +1,100 @@ +******************* +Koncepcja aplikacji +******************* + +Do najważniejszych problemów debaty publicznej niewątpliwie zalicza się częste opieranie argumentacji na nieweryfikowalnych lub nieaktualnych danych. + +Informacje posiadane przez organy administracji publicznej są skarbnicą wiedzy. Ich skuteczne wykorzystanie pozwoliłoby rozwiać wiele pojawiających się wątpliwości. Niestety, forma ich przechowywania i udostępniania często uniemożliwia łatwe ich odczytanie oraz intepretację, w szczególności przy użyciu technik cyfrowych. + +Obywatelskie fedrowanie danych jest projektem powstałym w odpowiedzi na to wyzwanie. Ma na celu usystematyzowanie dużej liczby informacji spływających od instytucji publicznych oraz zapisanie ich w formie łatwej do analizy, zarówno przez człowieka, jak i maszynę. To obywatele-wolontariusze, którym zależy na jakości życia publicznego w Polsce, czytają udzielone przez organy odpowiedzi i uzupełniają bazę danych poprzez wykorzystanie intuicyjnego mechanizmu ankiet. Zebrane i uporządkowane dane służą następnie do przeprowadzania badań, które to przyczyniają się do wzrostu świadomości społecznej i poprawy jakości rządzenia. + +Cele społeczne +---- + +* Szybka i zbiorowa analiza danych nieistniejących w żadnych repozytoriach i nie istniejących w formie możliwej do odczytu maszynowego. Do wykorzystywania w kampaniach rzeczniczych lub jako dowody w systemie tworzenia prawa. +* Masowa edukacja obywatelska na temat tego, jakie informacje można uzyskać od władz i jak wyglądają ich odpowiedzi oraz korespondencja z nimi, a także jak sprawdzać wypowiedzi pojawiające się w debacie publicznej. + +Cele dodatkowe +---- + +Aplikacja uniwersalna, do przystosowania dla różnych akcji przez różne organizacje. + +Zasada działania +---- + +W pierwszej kolejności użycie aplikacji wymaga dostarczenia danych adresowych instytucji, co zapewnia moduł :ref:`institutions`. Po wypełnieniu bazy adresowej wymagane jest utworzenie monitoringu (zob. :ref:`monitorings`), co zapewnia jednocześnie utworzenie spraw (zob. :ref:`cases`), a także wysłanie stworzenie w nich pierwszych listów (zob. :ref:`letters`). + +Wysyłka listów systemu odbywa się z wykorzystaniem poczty elektronicznej. Zazwyczaj jeden wzórw listu jest kierowany do kilkudziesięciu podmiotów. W odpowiedzi urząd ma obowiązek udzielenia nam odpowiedzi w formie i sposób określony w wniosku - na dedykowany adres e-mail. Wiadomośći są interpretowane i pobierane do systemu przez moduł :ref:`letters`, który zapewnia również przypisanie korespondencji do danej sprawy (zob. :ref:`cases`), która związana jest z konkretnym urzędem. + +Po zarejestrowaniu odpowiedniej ilości odpowiedzi możliwe konieczne jest utworzenie w monitoringu stworzenia kwestionariusza (zob. :ref:`questionaries`), a następnie na jego podstawie w licznych sprawach utworzenie zadań (zob. :ref:`tasks`). Wówczas dane są przetwarznae przez użytkowników, co zostało przedstawione na diagramie: + +.. figure:: https://www.websequencediagrams.com/cgi-bin/cdraw?lz=RmVkZXItPlVyesSFZDogd25pb3NlayBvIGluZm9ybWFjamUgcHVibGljem7EhSDigJMgZS1tYWlsCgAtBi0-AD0FOiBvZHBvd2llZMW6ABkMT2J5d2F0ZWwgMQAgCXphcHl0YW5pZSBvIHN0YW4gc3ByYXd5AFYFc3Ryb25hIFdXV1cKAIETBwA4CgBXDXVyesSZZHUgaSBhbmtpZXRhAGEKMgAqQTIAOTJ3eXBlxYJuaW9uYQCBCQkAglUHAIIaB3BvcsOzd24AgXUFAIEuBgCBPQgKCm9wdCAKICAgIACBbQhwZXJhdG8AMQV3aWFkb21pZQCCLAZyb3piaWXFvG5vxZtjaWFjaAAyBQAoCAAuDG9jZQCBAwkgaQCDFwl6aQBuCQAsDgCBQAlicmEAgToLZW5kCgCDAwkAgQ4JYXJrdXN6IGthbGt1bGFjeWpueSB6IGRhbnltaQo&s=default + :alt: Diagram sekwencji procesu analizy danych + +.. code:: + + Feder->Urząd: wniosek o informacje publiczną – e-mail + Urząd->Feder: odpowiedź – e-mail + Obywatel 1->Feder: zapytanie o stan sprawy – strona WWWW + Feder->Obywatel 1: odpowiedź urzędu i ankieta + Obywatel 2->Feder: zapytanie o stan sprawy – strona WWWW + Feder->Obywatel 2: odpowiedź urzędu i ankieta + Obywatel 2->Feder: wypełniona ankieta + Feder->Feder: porównanie ankiet urzędu + + opt + Feder->Operator: powiadomienie o rozbieżnościach + Operator->Operator: ocena ankiet i odpowiedzi urzędu + Operator->Feder: wybrana ankieta + end + + Feder->Operator: arkusz kalkulacyjny z danymi + + +System wyposażony winien być w mechanizm weryfikacji rozbieżności w ankietach, gdyby dochodziło do rozbieżnych interpretacji udzielonych odpowiedzi. Wówczas operator dokonuje wyboru właściwej ankiety, albo zgłasza odpowiedzi własne. + +Ankiety związane z danym kwestionariuszem mogą być wyeksportowane i analizowane z wykorzystaniem właściwych narzędzi. + +Przykłady zastosowań +---- + +Przepisywanie skróconych informacji i dostarczanie danych liczbowych +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +W 2012 Sieć Obywatelska Watchdog Polska włączyła się w kampanię przeciw zmianom w ustawie o zgromadzeniach. Zmiany wprowadzano pod wpływem zamieszek przy okazji Dnia Niepodległości w Warszawie. Miały one zwiększać kontrolę i de facto nakładać duże obowiązki na organizatorów zgromadzeń. Celem zbierania danych było uzyskanie informacji możliwych do pokazania parlamentarzystom, o tym że zmiany które chcą wprowadzić dotkną także organizatorów zgromadzeń w małych miejscowościach. Przekaz miał uświadomić, że zmian prawa nie można dokonywać bez widzenia całości obszaru, którego będą one dotyczyły oraz że zmiany mogą zamrozić i tak niewielką aktywność obywatelską. + +Aby dowiedzieć się jak wglądają zgromadzenia w małych miejscowościach (duże często mają rejestr w formie możliwej do odczytu w BIPie), Sieć Obywatelska Watchdog Polska wysłała wniosek o informację do wybranych urzędów gmin o:. + +* skany wszystkich wniosków zgłaszających zgromadzenie za lata 2010-2012 +* skany ewentualnych decyzji odmawiających zgłaszanie zgromadzenia za lata 2010-2012 + +Z otrzymanych odpowiedzi można było uzyskać głównie dane jakościowe: +* jakie podmioty zgłaszają zgromadzenia (czy są to osoby indywidualne, związki zawodowe, kościoły, organizacje) +* w jakiej sprawie są te zgromadzenia organizowane oraz dane ilościowe +* ile rocznie zgłasza się zgromadzeń (zwłaszcza w mniejszych miejscowościach) + +Dostarczanie danych liczbowych +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +W 2012 roku zwiększyła się nieco aktywność obywatelska w zakresie wnioskowania o informację. Był to wynik błędów rządu przy nowelizacji ustawy o dostępie do informacji publicznej i dużego nagłośnienia medialnego. Częściowo zapewne także wynik aktywności Sieci Obywatelskiej Watchdog Polska i innych organizacji. Nie bez znaczenia jest, że firmy zbierające dane, nauczyły się korzystać z prawa do informacji, co szczególnie oburza urzędników. Lobbing urzędników był i jest na tyle skuteczny, że coraz więcej szanowanych osób zabierających głos w debacie publicznej powtarza sformułowanie o „nadużywaniu prawa do informacji” Ponieważ może to skutkować realnymi zmianami w prawie, Sieć Obywatelska Watchdog Polska wysłała do wszystkich urzędów gmin (2500) wniosek, który miał zweryfikować jaki jest faktyczny stan wnioskowania i zbadać jakie dane są w ogóle dostępne. Wyniki pokazały, że realny poziom wnioskowania jest bardzo niski – od kilku do kilkudziesięciu wniosków rocznie (poza największymi miastami i ekstremalnymi sytuacjami), a wzrost pomiędzy 2011 i 2012 roku jest znikomy. + +Aby uzyskać te informacje, Sieć Obywatelka Watchdog Polska zadała następujące pytania: + +1. Ile wniosków o informację publiczną otrzymał urząd w 2011 roku +2. Ile wniosków o informację publiczną otrzymał urząd w 2012 roku +3. Udostępnienie ewidencji wniosków o informację publiczną za 2011 rok. +Jeżeli ewidencja prowadzona jest w formie elektronicznej, żądamy udostępnienia w postaci pliku w formacie dokumentu tekstowego lub arkusza kalkulacyjnego. Jeżeli ewidencja/rejestr nie jest prowadzony w formie elektronicznej, wnosimy o udostępnienie informacji w postaci skanu, z dokonaniem niezbędnych wyłączeń dotyczących ochrony prywatności wnioskujących osób. +4. Udostępnienie ewidencji wniosków o informację publiczną za 2012 rok. Jeżeli ewidencja prowadzona jest w formie elektronicznej, żądamy udostępnienia w postaci pliku w formacie dokumentu tekstowego lub arkusza kalkulacyjnego. Jeżeli ewidencja/rejestr nie jest prowadzony w formie elektronicznej, wnosimy o udostępnienie informacji w postaci skanu, z dokonaniem niezbędnych wyłączeń dotyczących ochrony prywatności wnioskujących osób. + +Dane, które można uzyskać dzięki masowej analizie obywatelskiej to: + +* Ile wniosków wpłynęło w 2011 roku? LICZBA +* Ile wniosków wpłynęło w 2012 roku? LICZBA +* Czy załączona została ewidencja wniosków za 2011 rok? TAK/NIE +* Czy załączona została ewidencja wniosków za 2012 rok? TAK/NIE +* Kiedy wniosek został zrealizowany? FORMAT DATY +* Czy urząd twierdzi, że żądanie dotyczy informacji przetworzonej? odhaczenie jeśli tak +* Czy za przygotowanie informacji zażądano opłaty/sugerowano opłatę? odhaczenie jeśli tak +* Czy napisano, że konieczne jest przedłużenie czasu potrzebnego na odpowiedź? odhaczenie jeśli tak +* Czy w tej gminie wystąpiła sytuacja braku ewidencji, ale w zamian pojawiły się skany wniosków? odhaczenie jeśli tak +* Czy w tej gminie wystąpiła sytuacja braku ewidencji, ale w zamian w odpowiedzi pojawił się opis złożonych wniosków? odhaczenie jeśli tak diff --git a/docs/make.bat b/docs/make.bat index 6f2c792b4..e870c57b4 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -99,9 +99,9 @@ if "%1" == "qthelp" ( echo. echo.Build finished; now you can run "qcollectiongenerator" with the ^ .qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\feder.qhcp + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\watchdog_kj_kultura.qhcp echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\feder.ghc + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\watchdog_kj_kultura.ghc goto end ) diff --git a/docs/modules/alerts.rst b/docs/modules/alerts.rst new file mode 100644 index 000000000..4c70fd671 --- /dev/null +++ b/docs/modules/alerts.rst @@ -0,0 +1,47 @@ +.. _alerts: + +************************** +Powiadomienia +************************** + +Założenia +######### + +Moduł stanowi komponent powiadomień do operatora o konieczności podjęcia akcji w systemie. Takie powiadomienia mogą być kierowane w związku z rozbieżnością w odpowiedziach, ale także ze względu na konieczność ochrony prywatności, gdyby jakiś urząd dokonał nieuprawnionego ujawnienia danych prywatnych. + + +Dane testowe +############ + +Dla modułu nie możliwe jest w środowisku deweloperskim dynamicznie wygenerowanie generowanych danych testowych. + + .. todo:: + Opracować generowanie danych testowych. + +Architektura +############ + +Model +----- + +.. automodule:: feder.alerts.models + :members: + + +Panel administracyjny +--------------------- + +.. automodule:: feder.alerts.admin + :members: + +Procesorzy kontekstu +-------------------- + +.. automodule:: feder.alerts.context_processors + :members: + +Widoki +-------------------- + +.. automodule:: feder.alerts.views + :members: diff --git a/docs/modules/cases.rst b/docs/modules/cases.rst new file mode 100644 index 000000000..dfa7573b9 --- /dev/null +++ b/docs/modules/cases.rst @@ -0,0 +1,46 @@ +.. _cases: + +************************** +Sprawy +************************** + +Założenia +######### + +Moduł odpowiedzialny jest za mechanizm "wątków" odnoszących się do konkretnego zapytania skierowanego do konkretnego urzędu. Każda sprawa jest związana tylko z jednym monitoringiem i jednym zapytaniem. W obrębie sprawy mogą być agregowane informacje różnej kategorii. + +Dane testowe +############ + +Dla modułu nie możliwe jest w środowisku deweloperskim dynamicznie wygenerowanie generowanych danych testowych. + + .. todo:: + Opracować generowanie danych testowych. + +Architektura +############ + +Model +----- + +.. automodule:: feder.cases.models + :members: + + +Panel administracyjny +--------------------- + +.. automodule:: feder.cases.admin + :members: + +Procesorzy kontekstu +-------------------- + +.. automodule:: feder.cases.context_processors + :members: + +Widoki +-------------------- + +.. automodule:: feder.cases.views + :members: diff --git a/docs/modules/institutions.rst b/docs/modules/institutions.rst new file mode 100644 index 000000000..868460711 --- /dev/null +++ b/docs/modules/institutions.rst @@ -0,0 +1,46 @@ +.. _institutions: + +************************** +Instytucje +************************** + +Założenia +######### + +Moduł stanowi mechanizm gromadzenia danych adresowych o instytucjach i przedstawienie spraw w jakich dany urząd jest zaaganżowany. + +Dane testowe +############ + +Dla modułu nie możliwe jest w środowisku deweloperskim dynamicznie wygenerowanie generowanych danych testowych. + + .. todo:: + Opracować generowanie danych testowych. + +Architektura +############ + +Model +----- + +.. automodule:: feder.institutions.models + :members: + + +Panel administracyjny +--------------------- + +.. automodule:: feder.institutions.admin + :members: + +Procesorzy kontekstu +-------------------- + +.. automodule:: feder.institutions.context_processors + :members: + +Widoki +-------------------- + +.. automodule:: feder.institutions.views + :members: diff --git a/docs/modules/letters.rst b/docs/modules/letters.rst new file mode 100644 index 000000000..555d90e7d --- /dev/null +++ b/docs/modules/letters.rst @@ -0,0 +1,48 @@ +.. _letters: + +************************** +Listy +************************** + +Założenia +######### + +Moduł odpowiedzialny za indywidualny komunikat wymieniony pomiedzy systemem, a urzędem. Zapewnia odbiór korespondencji w formie e-mailowej wraz z załącznikami i jej publikacji. + +Odbiór korespondencji w formie e-mailowej realizowany jest z wsparciem aplikacji `django-mailbox `_ . + +Dane testowe +############ + +Dla modułu nie możliwe jest w środowisku deweloperskim dynamicznie wygenerowanie generowanych danych testowych. + + .. todo:: + Opracować generowanie danych testowych. + +Architektura +############ + +Model +----- + +.. automodule:: feder.letters.models + :members: + + +Panel administracyjny +--------------------- + +.. automodule:: feder.letters.admin + :members: + +Procesorzy kontekstu +-------------------- + +.. automodule:: feder.letters.context_processors + :members: + +Widoki +-------------------- + +.. automodule:: feder.letters.views + :members: diff --git a/docs/modules/monitorings.rst b/docs/modules/monitorings.rst new file mode 100644 index 000000000..258543407 --- /dev/null +++ b/docs/modules/monitorings.rst @@ -0,0 +1,46 @@ +.. _monitorings: + +************************** +Monitoringi +************************** + +Założenia +######### + +Moduł stanowi komponent, który agreguje sprawy związane z różnymi urzędami, które odnoszą się do zbiernia informacji tej samej kategorii. Zatem monitoringiem będzie np. zainteresowanie wysoką opłaty za śmieci w Polsce. Na tej postawie system tworzy liczne sprawy dla każdego urzędu, który ma być objęty badaniem. + +Dane testowe +############ + +Dla modułu nie możliwe jest w środowisku deweloperskim dynamicznie wygenerowanie generowanych danych testowych. + + .. todo:: + Opracować generowanie danych testowych. + +Architektura +############ + +Model +----- + +.. automodule:: feder.monitorings.models + :members: + + +Panel administracyjny +--------------------- + +.. automodule:: feder.monitorings.admin + :members: + +Procesorzy kontekstu +-------------------- + +.. automodule:: feder.monitorings.context_processors + :members: + +Widoki +-------------------- + +.. automodule:: feder.monitorings.views + :members: diff --git a/docs/modules/questionaries.rst b/docs/modules/questionaries.rst new file mode 100644 index 000000000..bef237513 --- /dev/null +++ b/docs/modules/questionaries.rst @@ -0,0 +1,51 @@ +.. _questionaries: + +************************** +Kwestionariusze +************************** + +Założenia +######### + +Moduł stanowi mechanizm analizy danych do postaci zagregowanej. + +Encja "kwestionariusz" (``Questionary``) zapewnia definicje na poziomie monitoringu na jakie pytania użytkownik ma odpowiedzieć w ramach opracowania danych w konkretnej sprawie. + +Encja "pytanie" (``Question``) zapewnia definicje konkretnego pytania - części składowego pytania, a także określa kolejności pytań występujących w kwestionariuszu. Każde pytanie może mieć różny format (pytanie tekstowe, pytanie wielokrotnego wyboru itp.), dzięki mechanizmowi `modulator`. + + +Dane testowe +############ + +Dla modułu nie możliwe jest w środowisku deweloperskim dynamicznie wygenerowanie generowanych danych testowych. + + .. todo:: + Opracować generowanie danych testowych. + +Architektura +############ + +Model +----- + +.. automodule:: feder.questionaries.models + :members: + + +Panel administracyjny +--------------------- + +.. automodule:: feder.questionaries.admin + :members: + +Procesorzy kontekstu +-------------------- + +.. automodule:: feder.questionaries.context_processors + :members: + +Widoki +-------------------- + +.. automodule:: feder.questionaries.views + :members: diff --git a/docs/modules/tasks.rst b/docs/modules/tasks.rst new file mode 100644 index 000000000..4279d899a --- /dev/null +++ b/docs/modules/tasks.rst @@ -0,0 +1,58 @@ +.. _tasks: + +************************** +Zadania +************************** + +Założenia +######### + +Moduł stanowi komponent zlecenia dla użytkownika opracowania danego kwestionariusza w danym monitoringu. Utworzony winien być w danej sprawie w momencie, gdy istnieje w niej jakakolwiek korespondencja. + +Encja "Task" (``Task`` ) stanowi indywidualne zlecenie wykonania opracowania informacji przesłanych przez urząd zgodnie z określonym kwestionariuszem. + +Encja "Ankieta" (``Survey``) zapewnia zagregowanie informacji stanowiących wypełnienie przez danego użytkownika danego kwestionariusza, co stanowi realizacje wybranego zadania. + +Encja "Odpowiedź" (``Answer``) stanowi odpowiedź na konkretne pytanie w danej ankiecie. + +Relacje pomiędzy encjami modułu zadania i kwestionariusz został przedstawiony na diagramie: + +.. figure:: _images/tasks_model.svg + :alt: Model relacji encji modułu zadań i kwestionariuszy + + +Dane testowe +############ + +Dla modułu nie możliwe jest w środowisku deweloperskim dynamicznie wygenerowanie generowanych danych testowych. + + .. todo:: + Opracować generowanie danych testowych. + +Architektura +############ + +Model +----- + +.. automodule:: feder.tasks.models + :members: + + +Panel administracyjny +--------------------- + +.. automodule:: feder.tasks.admin + :members: + +Procesorzy kontekstu +-------------------- + +.. automodule:: feder.tasks.context_processors + :members: + +Widoki +-------------------- + +.. automodule:: feder.tasks.views + :members: diff --git a/docs/modules/teryt.rst b/docs/modules/teryt.rst new file mode 100644 index 000000000..4761f105d --- /dev/null +++ b/docs/modules/teryt.rst @@ -0,0 +1,46 @@ +.. _teryt: + +********************************* +Jednostki podziału terytorialnego +********************************* + +Założenia +######### + +Moduł dostarcza informacje na temat podziału terytorialnego w Polsce. Zapewnia przegląd instytucji w danym regionie. + +Dane testowe +############ + +Dla modułu nie możliwe jest w środowisku deweloperskim dynamicznie wygenerowanie generowanych danych testowych. + + .. todo:: + Opracować generowanie danych testowych. + +Architektura +############ + +Model +----- + +.. automodule:: feder.teryt.models + :members: + + +Panel administracyjny +--------------------- + +.. automodule:: feder.teryt.admin + :members: + +Procesorzy kontekstu +-------------------- + +.. automodule:: feder.teryt.context_processors + :members: + +Widoki +-------------------- + +.. automodule:: feder.teryt.views + :members: diff --git a/requirements/doc.txt b/requirements/doc.txt new file mode 100644 index 000000000..b77c532f1 --- /dev/null +++ b/requirements/doc.txt @@ -0,0 +1 @@ +sphinxcontrib-programoutput==0.8