diff options
author | Evgeny Fadeev <evgeny.fadeev@gmail.com> | 2010-06-25 19:28:38 -0400 |
---|---|---|
committer | Evgeny Fadeev <evgeny.fadeev@gmail.com> | 2010-06-25 19:28:38 -0400 |
commit | 1e03a6c00adc0da43c2dbf8a4856f11b6cc1d138 (patch) | |
tree | 130af381775f31edf92b548549813350364a7827 | |
parent | e4dc9a9229205b9bbdc58a62b0411685fecf0f82 (diff) | |
download | askbot-1e03a6c00adc0da43c2dbf8a4856f11b6cc1d138.tar.gz askbot-1e03a6c00adc0da43c2dbf8a4856f11b6cc1d138.tar.bz2 askbot-1e03a6c00adc0da43c2dbf8a4856f11b6cc1d138.zip |
added beginnings of developer documentation
-rw-r--r-- | askbot/__init__.py | 27 | ||||
-rw-r--r-- | askbot/admin.py | 16 | ||||
-rw-r--r-- | askbot/doc/source/conf.py | 27 | ||||
-rw-r--r-- | askbot/doc/source/devel/__init__.rst | 1 | ||||
-rw-r--r-- | askbot/doc/source/devel/admin.rst | 3 | ||||
-rw-r--r-- | askbot/doc/source/devel/models.rst | 3 | ||||
-rw-r--r-- | askbot/doc/source/devel/views/__init__.rst | 3 | ||||
-rw-r--r-- | askbot/doc/source/devel/views/commands.rst | 3 | ||||
-rw-r--r-- | askbot/doc/source/devel/views/meta.rst | 3 | ||||
-rw-r--r-- | askbot/doc/source/devel/views/readers.rst | 3 | ||||
-rw-r--r-- | askbot/doc/source/devel/views/users.rst | 4 | ||||
-rw-r--r-- | askbot/doc/source/devel/views/writers.rst | 4 | ||||
-rw-r--r-- | askbot/tests.py | 11 | ||||
-rw-r--r-- | askbot/views/__init__.py | 16 | ||||
-rw-r--r-- | askbot/views/commands.py | 16 | ||||
-rw-r--r-- | askbot/views/meta.py | 8 | ||||
-rw-r--r-- | askbot/views/readers.py | 10 | ||||
-rw-r--r-- | askbot/views/users.py | 11 | ||||
-rw-r--r-- | askbot/views/writers.py | 8 |
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 |