Update docs

.gitignore

@@ -54,3 +54,4 @@ node_modules/
 
 # virtual environments
 .env
+docs/_build

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

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:

docs/administration/deploy.rst

@@ -0,0 +1,10 @@
+.. _deploy:
+
+*********
+Wdrożenie
+*********
+
+Został opublikowany playbook Ansible, który zapewnia wdrożenie aplikacji.
+
+ .. todo::
+    Publikacja Playbooka

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.

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

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,23 +254,24 @@
 # 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 ------------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (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)