From 4f4247ea9d65f50daa32f6c1f3740641e2eadd52 Mon Sep 17 00:00:00 2001
From: Jan Dittberner <jan@dittberner.info>
Date: Sat, 31 May 2014 16:12:36 +0200
Subject: [PATCH] add documentation for gvaldap project code

---
 docs/code.rst                          | 57 +++++++++++++++++++++++++-
 gvaldap/gvaldap/__init__.py            |  3 ++
 gvaldap/gvaldap/celery.py              | 12 +++---
 gvaldap/gvaldap/settings/__init__.py   |  4 +-
 gvaldap/gvaldap/settings/base.py       | 15 ++++++-
 gvaldap/gvaldap/settings/local.py      |  5 ++-
 gvaldap/gvaldap/settings/production.py |  5 ++-
 gvaldap/gvaldap/settings/test.py       |  4 ++
 gvaldap/gvaldap/urls.py                |  5 +++
 gvaldap/gvaldap/wsgi.py                |  2 +-
 10 files changed, 100 insertions(+), 12 deletions(-)

diff --git a/docs/code.rst b/docs/code.rst
index 1b90499..9001a7b 100644
--- a/docs/code.rst
+++ b/docs/code.rst
@@ -4,9 +4,64 @@ Code documentation
 
 .. index:: Django
 
-gvaldap is implemented as a set of `Django`_ apps.
+gvaldap is implemented as `Django`_ project and provides some `Celery`_ tasks.
 
 .. _Django: https://www.djangoproject.com/
+.. _Celery: http://www.celeryproject.org/
+
+
+The project module :py:mod:`gvaldap`
+====================================
+
+.. automodule:: gvaldap
+
+
+:py:mod:`gvaldap.celery`
+------------------------
+
+.. automodule:: gvaldap.celery
+   :members:
+
+
+:py:mod:`gvaldap.urls`
+----------------------
+
+.. automodule:: gvaldap.urls
+
+
+:py:mod:`gvaldap.wsgi`
+----------------------
+
+.. automodule:: gvaldap.wsgi
+   :members:
+
+
+:py:mod:`gvaldap.settings`
+--------------------------
+
+.. automodule:: gvaldap.settings
+
+:py:mod:`gvaldap.settings.base`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: gvaldap.settings.base
+   :members:
+
+:py:mod:`gvaldap.settings.local`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: gvaldap.settings.local
+
+:py:mod:`gvaldap.settings.production`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: gvaldap.settings.production
+
+:py:mod:`gvaldap.settings.test`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: gvaldap.settings.test
+
 
 
 :py:mod:`ldapentities` app
diff --git a/gvaldap/gvaldap/__init__.py b/gvaldap/gvaldap/__init__.py
index e69de29..62a61ef 100644
--- a/gvaldap/gvaldap/__init__.py
+++ b/gvaldap/gvaldap/__init__.py
@@ -0,0 +1,3 @@
+"""
+This is the gvaldap project module.
+"""
diff --git a/gvaldap/gvaldap/celery.py b/gvaldap/gvaldap/celery.py
index fd9a616..e9a2f75 100644
--- a/gvaldap/gvaldap/celery.py
+++ b/gvaldap/gvaldap/celery.py
@@ -1,3 +1,9 @@
+"""
+This module defines the Celery_ app for gvaldap.
+
+.. _Celery: http://www.celeryproject.org/
+
+"""
 from __future__ import absolute_import
 
 import os
@@ -10,12 +16,8 @@ os.environ.setdefault('DJANGO_SETTINGS_MODULE',
                       'gvaldap.settings.production')
 
 
+#: The Celery application
 app = Celery('gvaldap')
 
 app.config_from_object('django.conf:settings')
 app.autodiscover_tasks(lambda: settings.INSTALLED_APPS)
-
-
-@app.task(bind=True)
-def debug_task(self):
-    print('Request: {0!r}'.format(self.request))
diff --git a/gvaldap/gvaldap/settings/__init__.py b/gvaldap/gvaldap/settings/__init__.py
index 8b13789..4f53a5e 100644
--- a/gvaldap/gvaldap/settings/__init__.py
+++ b/gvaldap/gvaldap/settings/__init__.py
@@ -1 +1,3 @@
-
+"""
+This module contains settings for various environments.
+"""
diff --git a/gvaldap/gvaldap/settings/base.py b/gvaldap/gvaldap/settings/base.py
index 70de0e7..46c8740 100644
--- a/gvaldap/gvaldap/settings/base.py
+++ b/gvaldap/gvaldap/settings/base.py
@@ -1,5 +1,9 @@
-"""Common settings and globals."""
+# -*- coding: utf-8 -*-
 # pymode:lint_ignore=E501
+"""
+Common settings and globals.
+
+"""
 
 
 from os.path import abspath, basename, dirname, join, normpath
@@ -12,7 +16,14 @@ from django.core.exceptions import ImproperlyConfigured
 
 
 def get_env_setting(setting):
-    """ Get the environment setting or return exception """
+    """
+    Get the environment setting or return exception.
+
+    :param str setting: name of an environment setting
+    :raises ImproperlyConfigured: if the environment setting is not defined
+    :return: environment setting value
+    :rtype: str
+    """
     try:
         return environ[setting]
     except KeyError:
diff --git a/gvaldap/gvaldap/settings/local.py b/gvaldap/gvaldap/settings/local.py
index 3329842..8a8d441 100644
--- a/gvaldap/gvaldap/settings/local.py
+++ b/gvaldap/gvaldap/settings/local.py
@@ -1,5 +1,8 @@
-"""Development settings and globals."""
 # pymode:lint_ignore=W0401,E501
+"""
+Development settings and globals based on :py:mod:`gvaldap.settings.base`.
+
+"""
 
 from __future__ import absolute_import
 
diff --git a/gvaldap/gvaldap/settings/production.py b/gvaldap/gvaldap/settings/production.py
index 7c9b280..288e1db 100644
--- a/gvaldap/gvaldap/settings/production.py
+++ b/gvaldap/gvaldap/settings/production.py
@@ -1,5 +1,8 @@
-"""Production settings and globals."""
 # pymode:lint_ignore=W0401,E501
+"""
+Production settings and globals based on :py:mod:`gvaldap.settings.base`.
+
+"""
 
 from __future__ import absolute_import
 
diff --git a/gvaldap/gvaldap/settings/test.py b/gvaldap/gvaldap/settings/test.py
index e510233..c39ee49 100644
--- a/gvaldap/gvaldap/settings/test.py
+++ b/gvaldap/gvaldap/settings/test.py
@@ -1,4 +1,8 @@
 # pymode:lint_ignore=W0401
+"""
+Test settings based on :py:mod:`gvaldap.settings.base`.
+
+"""
 from __future__ import absolute_import
 
 from .base import *
diff --git a/gvaldap/gvaldap/urls.py b/gvaldap/gvaldap/urls.py
index 120582d..37d1d10 100644
--- a/gvaldap/gvaldap/urls.py
+++ b/gvaldap/gvaldap/urls.py
@@ -1,3 +1,8 @@
+"""
+This module defines the main URLConf for gvaldap.
+
+"""
+
 from django.conf.urls import patterns, include, url
 from django.conf import settings
 
diff --git a/gvaldap/gvaldap/wsgi.py b/gvaldap/gvaldap/wsgi.py
index 29b3554..af02caa 100644
--- a/gvaldap/gvaldap/wsgi.py
+++ b/gvaldap/gvaldap/wsgi.py
@@ -26,10 +26,10 @@ path.append(SITE_ROOT)
 # os.environ["DJANGO_SETTINGS_MODULE"] = "jajaja.settings"
 os.environ.setdefault("DJANGO_SETTINGS_MODULE", "gvaldap.settings.production")
 
+from django.core.wsgi import get_wsgi_application
 # This application object is used by any WSGI server configured to use this
 # file. This includes Django's development server, if the WSGI_APPLICATION
 # setting points here.
-from django.core.wsgi import get_wsgi_application
 application = get_wsgi_application()
 
 # Apply WSGI middleware here.