19 files changed, 153 insertions, 24 deletions
diff --git a/askbot/__init__.py b/askbot/__init__.py
index 90c491d8..8368ecf4 100644
--- a/askbot/__init__.py
+++ b/askbot/__init__.py
@@ -1,14 +1,15 @@
-"""aksbot askbot module
 """
-__all__ = [
-    'admin',
-    'auth',
-    'const',
-    'feed',
-    'forms',
-    'managers',
-    'models',
-    'sitemap',
-    'urls',
-    'views'
-]
+.. askbot-module:
+
+:mod:`askbot` -- the Django Q&A forum application
+=================================================
+
+This module encapsulates the askbot application and consists of the following sub-modules:
+
+* :ref:`admin <askbot.admin>` - connector of models to Django admin interface
+* :ref:`views <askbot.views>` - all view functions (controllers in MVC terminology)
+
+.. moduleauthor:: Mike Chen
+.. moduleauthor:: Evgeny Fadeev <evgeny.fadeev@gmail.com>
+
+"""
diff --git a/askbot/admin.py b/askbot/admin.py
index 1ecfa3aa..58e03102 100644
--- a/askbot/admin.py
+++ b/askbot/admin.py
@@ -1,7 +1,15 @@
+# -*- coding: utf-8 -*-
 """
-linking of askbot modules to admin interface
+.. _askbot.admin:
+
+:mod:`askbot.admin` - connector to standard Django admin interface
+===================================================================
+
+Add more classes subclassing ``django.contrib.admin.Model``
+
+Names of the classes must be like `SomeModelAdmin`, where `SomeModel` must 
+exactly match name of the model used in the project
 """
-# -*- coding: utf-8 -*-
 from django.contrib import admin
 from askbot import models
 
@@ -14,7 +22,7 @@ class QuestionAdmin(admin.ModelAdmin):
 class TagAdmin(admin.ModelAdmin):
     """Tag admin class"""
 
-class Answerdmin(admin.ModelAdmin):
+class AnswerAdmin(admin.ModelAdmin):
     """Answer admin class"""
 
 class CommentAdmin(admin.ModelAdmin):
@@ -58,7 +66,7 @@ class ActivityAdmin(admin.ModelAdmin):
     
 admin.site.register(models.Question, QuestionAdmin)
 admin.site.register(models.Tag, TagAdmin)
-admin.site.register(models.Answer, Answerdmin)
+admin.site.register(models.Answer, AnswerAdmin)
 admin.site.register(models.Comment, CommentAdmin)
 admin.site.register(models.Vote, VoteAdmin)
 admin.site.register(models.FlaggedItem, FlaggedItemAdmin)
diff --git a/askbot/doc/source/conf.py b/askbot/doc/source/conf.py
index c6382c51..da743b4f 100644
--- a/askbot/doc/source/conf.py
+++ b/askbot/doc/source/conf.py
@@ -17,6 +17,27 @@ import sys, os
 # 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.
 #sys.path.append(os.path.abspath('.'))
+def parent_dir(start_path, levels_up = 1):
+    """returns path of a directory
+    levels_up relative to the start_path
+    """
+    if os.path.isfile(start_path):
+        start_path = os.path.dirname(start_path)
+    for i in range(levels_up):
+        start_path = os.path.dirname(start_path)
+    out_path = start_path
+    return out_path
+
+PROJECT_DIR = parent_dir(__file__, 3)
+PROJECT_MODULE = os.path.basename(PROJECT_DIR)
+os.environ['DJANGO_SETTINGS_MODULE'] = PROJECT_MODULE + '.settings'
+
+sys.path.append(PROJECT_DIR)
+#and a parent to project dir
+sys.path.append(parent_dir(__file__, 4))
+sys.path.append(parent_dir(__file__, 2))
+
+print sys.path
 
 # -- General configuration -----------------------------------------------------
 
@@ -41,7 +62,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Askbot'
-copyright = u'2010, Evgeny Fadeev'
+copyright = u'2010, Askbot Project'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -78,13 +99,13 @@ exclude_patterns = []
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
-#show_authors = False
+show_authors = True 
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
 # A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
+modindex_common_prefix = ['askbot.']
 
 
 # -- Options for HTML output ---------------------------------------------------
diff --git a/askbot/doc/source/devel/__init__.rst b/askbot/doc/source/devel/__init__.rst
new file mode 100644
index 00000000..3eae5545
--- /dev/null
+++ b/askbot/doc/source/devel/__init__.rst
@@ -0,0 +1 @@
+.. automodule:: askbot
diff --git a/askbot/doc/source/devel/admin.rst b/askbot/doc/source/devel/admin.rst
new file mode 100644
index 00000000..0a1337d3
--- /dev/null
+++ b/askbot/doc/source/devel/admin.rst
@@ -0,0 +1,3 @@
+.. automodule:: askbot.admin
+    :members:
+    :undoc-members:
diff --git a/askbot/doc/source/devel/models.rst b/askbot/doc/source/devel/models.rst
new file mode 100644
index 00000000..81ee38f5
--- /dev/null
+++ b/askbot/doc/source/devel/models.rst
@@ -0,0 +1,3 @@
+.. automodule:: askbot.models
+    :members:
+    :undoc-members:
diff --git a/askbot/doc/source/devel/views/__init__.rst b/askbot/doc/source/devel/views/__init__.rst
new file mode 100644
index 00000000..bd1f79e5
--- /dev/null
+++ b/askbot/doc/source/devel/views/__init__.rst
@@ -0,0 +1,3 @@
+.. automodule:: askbot.views
+    :members:
+    :undoc-members:
diff --git a/askbot/doc/source/devel/views/commands.rst b/askbot/doc/source/devel/views/commands.rst
new file mode 100644
index 00000000..565ce5c4
--- /dev/null
+++ b/askbot/doc/source/devel/views/commands.rst
@@ -0,0 +1,3 @@
+.. automodule:: askbot.views.commands
+    :members:
+    :undoc-members:
diff --git a/askbot/doc/source/devel/views/meta.rst b/askbot/doc/source/devel/views/meta.rst
new file mode 100644
index 00000000..452dac10
--- /dev/null
+++ b/askbot/doc/source/devel/views/meta.rst
@@ -0,0 +1,3 @@
+.. automodule:: askbot.views.meta
+    :members:
+    :undoc-members:
diff --git a/askbot/doc/source/devel/views/readers.rst b/askbot/doc/source/devel/views/readers.rst
new file mode 100644
index 00000000..63a99eb4
--- /dev/null
+++ b/askbot/doc/source/devel/views/readers.rst
@@ -0,0 +1,3 @@
+.. automodule:: askbot.views.readers
+    :members:
+    :undoc-members:
diff --git a/askbot/doc/source/devel/views/users.rst b/askbot/doc/source/devel/views/users.rst
new file mode 100644
index 00000000..e6271404
--- /dev/null
+++ b/askbot/doc/source/devel/views/users.rst
@@ -0,0 +1,4 @@
+.. automodule:: askbot.views.users
+    :members:
+    :undoc-members:
+
diff --git a/askbot/doc/source/devel/views/writers.rst b/askbot/doc/source/devel/views/writers.rst
new file mode 100644
index 00000000..1e5f8a7d
--- /dev/null
+++ b/askbot/doc/source/devel/views/writers.rst
@@ -0,0 +1,4 @@
+.. automodule:: askbot.views.writers
+    :members:
+    :undoc-members:
+
diff --git a/askbot/tests.py b/askbot/tests.py
index dcdf0782..10584ed1 100644
--- a/askbot/tests.py
+++ b/askbot/tests.py
@@ -1,3 +1,12 @@
+"""
+.. _tests:
+
+:mod:`tests` -- Module for testing Askbot 
+==========================================
+
+.. automodule:: tests 
+  .. moduleauthor:: Evgeny Fadeev <evgeny.fadeev@gmail.com>
+"""
 import datetime
 import time
 from django.test import TestCase
@@ -8,6 +17,8 @@ from askbot.models import EmailFeedSetting
 from askbot import const
 
 def create_user(username = None, email = None):
+    """Creates a user and sets default update subscription
+    settings"""
     user = User.objects.create_user(username, email)
     for feed_type in EmailFeedSetting.FEED_TYPES:
         feed = EmailFeedSetting(
diff --git a/askbot/views/__init__.py b/askbot/views/__init__.py
index 35b2acba..05fb0319 100644
--- a/askbot/views/__init__.py
+++ b/askbot/views/__init__.py
@@ -1,5 +1,19 @@
 """
-Forum views module
+.. _askbot.views:
+
+:mod:`askbot.views` - Django views for askbot
+=============================================
+
+This module provides `django view functions`_ necessary for the askbot project.
+
+Askbot views are subdivided into the following sub-modules:
+
+* :ref:`readers <askbot.views.readers>` - views that display but do not modify main textual content (Questions, Answers, Comments and Tag)
+* :ref:`writers <askbot.views.writers>` - generate forms that change main content 
+* :ref:`commands <askbot.views.commands>` - most Ajax command processors
+* :ref:`users <askbot.views.users>` - views generating user-specific content and the listing of site users
+* :ref:`meta <askbot.views.meta>` - remaining views (for example - badges, faq, privacy, etc. - may require some cleanup)
+
 """
 from askbot.views import readers
 from askbot.views import writers
diff --git a/askbot/views/commands.py b/askbot/views/commands.py
index 4e4347f2..7151ead1 100644
--- a/askbot/views/commands.py
+++ b/askbot/views/commands.py
@@ -1,3 +1,13 @@
+"""
+.. _askbot.views.commands:
+
+:mod:`askbot.views.commands` - most ajax processors for askbot
+===============================================================
+
+This module contains most (but not all) processors for Ajax requests. 
+Not so clear if this subdivision was necessary as separation of Ajax and non-ajax views
+is not always very clean.
+"""
 import datetime
 #todo: maybe eliminate usage of django.settings
 from django.conf import settings
@@ -16,10 +26,10 @@ from django.contrib.auth.decorators import login_required
 from askbot.utils.decorators import ajax_method, ajax_login_required
 import logging
 
-def vote(request, id):#todo: pretty incomprehensible view used by various ajax calls
-#issues: this subroutine is too long, contains many magic numbers and other issues
-#it's called "vote" but many actions processed here have nothing to do with voting
+def vote(request, id):
     """
+    todo: this subroutine needs serious refactoring it's too long and is hard to understand
+
     vote_type:
         acceptAnswer : 0,
         questionUpVote : 1,
diff --git a/askbot/views/meta.py b/askbot/views/meta.py
index 564b11e6..aa806096 100644
--- a/askbot/views/meta.py
+++ b/askbot/views/meta.py
@@ -1,3 +1,11 @@
+"""
+.. _askbot.views.meta:
+
+:mod:`askbot.views.meta` - "secondary" views for askbot
+===============================================================
+
+This module contains a collection of views displaying all sorts of secondary and mostly static content.
+"""
 from django.shortcuts import render_to_response, get_object_or_404
 from django.core.urlresolvers import reverse
 from django.template import RequestContext
diff --git a/askbot/views/readers.py b/askbot/views/readers.py
index 2d50fe44..9bcd435f 100644
--- a/askbot/views/readers.py
+++ b/askbot/views/readers.py
@@ -1,4 +1,14 @@
 # encoding:utf-8
+"""
+.. _askbot.views.readers:
+
+:mod:`askbot.views.readers` - read-only views for main textual content
+========================================================================
+
+By main textual content is meant - text of Questions, Answers and Comments.
+The "read-only" requirement here is not 100% strict, as for example "question" view does
+allow adding new comments via Ajax form post.
+"""
 import datetime
 import logging
 from urllib import unquote
diff --git a/askbot/views/users.py b/askbot/views/users.py
index 3709ee78..ca71328c 100644
--- a/askbot/views/users.py
+++ b/askbot/views/users.py
@@ -1,3 +1,14 @@
+"""
+.. _askbot.views.users:
+
+:mod:`askbot.views.users` - user-centric views for askbot
+===========================================================
+
+This module includes all views that are specific to a given user - his or her profile, 
+and other views showing profile-related information.
+
+Also this module includes the view listing all forum users.
+"""
 from django.contrib.auth.decorators import login_required
 from django.core.paginator import Paginator, EmptyPage, InvalidPage
 from django.template.defaultfilters import slugify
diff --git a/askbot/views/writers.py b/askbot/views/writers.py
index 4063e19a..2aa77a2c 100644
--- a/askbot/views/writers.py
+++ b/askbot/views/writers.py
@@ -1,4 +1,12 @@
 # encoding:utf-8
+"""
+.. _askbot.views.writers:
+
+:mod:`askbot.views.writers` - views diplaying and processing post forms
+=========================================================================
+
+This module contains views that allow adding, editing, and deleting main textual content.
+"""
 import os.path
 import time, datetime, random
 from django.core.files.storage import default_storage