Commits

Lukasz Balcerzak committed 3c4f111

Documentation and docstrings update

Comments (0)

Files changed (13)

docs/api/forms.rst

+.. _api-forms:
+
+=====
+Forms
+=====
+
+.. automodule:: projector.forms
+
+Return to :ref:`api`.
+
+
+.. _api-forms-project:
+
+
+.. form:: ProjectCreateForm
+
+ProjectCreateForm
+=================
+
+.. autoclass:: projector.forms.ProjectCreateForm
+   :members:
+
+
+.. form:: ProjectEditForm
+
+ProjectEditForm
+===============
+
+.. autoclass:: projector.forms.ProjectEditForm
+
+
+.. form:: ProjectForkForm
+
+ProjectForkForm
+===============
+
+.. autoclass:: projector.forms.ProjectForkForm
+   :members:
+
+
+.. form:: ConfigForm
+
+ConfigForm
+==========
+
+.. autoclass:: projector.forms.ConfigForm
+   :members:
+
+
+
+.. _api-forms-user:
+
+
+.. form:: UserProfileForm
+
+UserProfileForm
+===============
+
+.. autoclass:: projector.forms.UserProfileForm
+   :members:
+
+
+.. form:: ExternalForkWizard
+
+ExternalForkWizard
+==================
+
+.. autoclass:: projector.forms.ExternalForkWizard
+   :members:
+
+
+.. form:: UserConvertToTeamForm
+
+UserConvertToTeamForm
+=====================
+
+.. autoclass:: projector.forms.UserConvertToTeamForm
+   :members:
+
+
+.. form:: DashboardAddMemberForm
+
+DashboardAddMemberForm
+======================
+
+.. autoclass:: projector.forms.DashboardAddMemberForm
+   :members:
+

docs/api/index.rst

    :maxdepth: 3
 
    core/index.rst
+   forms
    managers
    models
    utils
    signals
+   views/index.rst
    

docs/api/views/index.rst

+.. _api-views:
+
+Views
+=====
+
+Return to :ref:`api`.
+
+.. toctree::
+   :maxdepth: 2
+
+   project
+   project_repository
+   users
+

docs/api/views/project.rst

+.. _api-views-project:
+
+=============
+Project views
+=============
+
+Return to :ref:`api-views`.
+
+.. automodule:: projector.views.project
+
+
+.. view:: ProjectView
+
+ProjectView
+===========
+
+.. autoclass:: projector.views.project.ProjectView
+   :members:
+
+
+.. view:: ProjectDetailView
+
+ProjectDetailView
+=================
+
+.. autoclass:: projector.views.project.ProjectDetailView
+   :members:
+   :show-inheritance:
+   :inherited-members:
+
+
+.. view:: ProjectListView
+
+ProjectListView
+===============
+
+.. autoclass:: projector.views.project.ProjectListView
+   :members:
+   :show-inheritance:
+   :inherited-members:
+
+
+.. view:: ProjectCreateView
+
+ProjectCreateView
+=================
+
+.. autoclass:: projector.views.project.ProjectCreateView
+   :members:
+   :show-inheritance:
+   :inherited-members:
+   
+
+.. view:: ProjectForkView
+
+ProjectForkView
+===============
+
+.. autoclass:: projector.views.project.ProjectForkView
+   :members:
+   :show-inheritance:
+   :inherited-members:
+

docs/api/views/project_repository.rst

+.. _api-views-project-repository:
+
+========================
+Project repository views
+========================
+
+Return to :ref:`api-views`.
+
+.. automodule:: projector.views.project_repository
+
+
+.. view:: RepositoryView
+
+RepositoryView
+==============
+
+.. autoclass:: projector.views.project_repository.RepositoryView
+   :members:
+   :show-inheritance:
+   :inherited-members:
+
+
+
+.. view:: RepositoryBrowse
+
+RepositoryBrowse
+================
+
+.. autoclass:: projector.views.project_repository.RepositoryBrowse
+   :members:
+   :show-inheritance:
+   :inherited-members:
+
+
+.. view:: RepositoryFileDiff
+
+RepositoryFileDiff
+==================
+
+.. autoclass:: projector.views.project_repository.RepositoryFileDiff
+   :members:
+   :show-inheritance:
+   :inherited-members:
+
+
+.. view:: RepositoryFileRaw
+
+RepositoryFileRaw
+=================
+
+.. autoclass:: projector.views.project_repository.RepositoryFileRaw
+   :members:
+   :show-inheritance:
+   :inherited-members:
+
+
+.. view:: RepositoryFileAnnotate
+
+RepositoryFileAnnotate
+======================
+
+.. autoclass:: projector.views.project_repository.RepositoryFileAnnotate
+   :members:
+   :show-inheritance:
+   :inherited-members:
+
+
+.. view:: RepositoryChangesetList
+
+RepositoryChangesetList
+=======================
+
+.. autoclass:: projector.views.project_repository.RepositoryChangesetList
+   :members:
+   :show-inheritance:
+   :inherited-members:
+
+
+.. view:: RepositoryChangesetDetail
+
+RepositoryChangesetDetail
+=========================
+
+.. autoclass:: projector.views.project_repository.RepositoryChangesetDetail
+   :members:
+   :show-inheritance:
+   :inherited-members:
+
+

docs/api/views/users.rst

+.. _api-views-users:
+
+===========
+Users views
+===========
+
+Return to :ref:`api-views`.
+
+.. automodule:: projector.views.users
+
+
+.. view:: UserListView
+
+UserListView
+============
+
+.. autoclass:: projector.views.users.UserListView
+   :members:
+
+
+.. view:: UserHomepageView
+
+UserHomepageView
+================
+
+.. autoclass:: projector.views.users.UserHomepageView
+   :members:
+
+
+.. view:: UserProfileDetailView
+
+UserProfileDetailView
+=====================
+
+.. autoclass:: projector.views.users.UserProfileDetailView
+   :members:
+
+
+.. view:: UserDashboardView
+
+UserDashboardView
+=================
+
+.. autoclass:: projector.views.users.UserDashboardView
+   :members:
+
+
+.. view:: UserDashboardForkView
+
+UserDashboardForkView
+=====================
+
+.. autoclass:: projector.views.users.UserDashboardForkView
+   :members:
+
+
+.. view:: UserDashboardConvert2TeamView
+
+UserDashboardConvert2TeamView
+=============================
+
+.. autoclass:: projector.views.users.UserDashboardConvert2TeamView
+   :members:
+
+
+.. view:: UserDashboardAddMember
+
+UserDashboardAddMember
+======================
+
+.. autoclass:: projector.views.users.UserDashboardAddMember
+   :members:
+
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc', 'exts']
 
+#autodoc_default_flags = ['show-inheritance', 'inherited-members']
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['templates']
 
         indextemplate = "pair: %s; error",
     )
     app.add_crossref_type(
+        directivename = "form",
+        rolename      = "form",
+        indextemplate = "pair: %s; form",
+    )
+    app.add_crossref_type(
         directivename = "manager",
         rolename      = "manager",
         indextemplate = "pair: %s; manager",

projector/forms.py

 
 
 class ConfigForm(forms.ModelForm):
+    """
+    ModelForm for :model:`Config`.
+    """
     changesets_paginate_by = forms.IntegerField(
         label=_('Changesets paginate by'), min_value=5, max_value=50)
 
 
 
 class UserConvertToTeamForm(forms.Form):
+    """
+    Simple form which converts user into :model:`Team`.
+
+    .. note::
+       User instance has to be set within a view::
+
+          def aview(request):
+              form = UserConvertToTeamForm(request.POST or None)
+              form.user = request.user
+              # ...
+
+    .. seealso:: :ref:`teamwork-membership-convert`
+
+    """
     confirm = forms.BooleanField(label=_('confirm'))
 
     def _get_user(self):
     user = property(_get_user, _set_user)
 
     def clean(self):
+        """
+        Cleans ``confirm`` field. If checked and ``user`` attribute has been
+        set, :manager:`TeamManager`'s method ``convert_from_user`` is called.
+        """
         if any(self.errors):
             return
         if not self.user:
 
 
 class ExternalForkWizard(FormWizard):
+    """
+    Form wizard which processes each step of external forking.
+
+    .. seealso:: :ref:`projects-forking-external`
+
+    """
 
     def done(self, request, form_list):
         form = form_list[1]
 
 
 class DashboardAddMemberForm(forms.Form):
+    """
+    Form providing ability to add user to the group. It is useful for users
+    converted into :model:`Team` to add new members.
+    """
     user = UserByNameField()
 
     def __init__(self, group, *args, **kwargs):
         return user
 
     def save(self, commit=True):
+        """
+        Adds chosen user to the group.
+        """
         user = self.cleaned_data['user']
         if commit:
             user.groups.add(self.group)

projector/models.py

     """
     Base user profile class for ``django-projector``.
     Would be abstract if ``AUTH_PROFILE_MODULE`` is not set or doesn't equal
-    with ``projector.UserProfile``.
+    to ``projector.UserProfile``.
     """
     activation_token = models.CharField(_('activation token'), max_length=32,
         editable=False)

projector/views/project.py

     Logic should be implemented at ``response`` method.
 
     Would check necessary permissions defined by class attributes: ``perms``,
-    ``perms_POST`` and ``perms_POST``. ``perms`` are always checked,
-    ``perms_POST`` are additional checks which would be made for ``GET`` method
-    requests only and ``perms_POST`` would be made for ``POST`` method requests.
-    ``perms_private`` would be checked for private projects only.
+    ``perms_GET`` and ``perms_POST``.
+
+    ``perms`` are always checked, ``perms_POST`` are additional checks which
+    would be made for ``GET`` method requests only and ``perms_POST`` would be
+    made for ``POST`` method requests.  ``perms_private`` would be checked for
+    private projects only.
+
+    .. note::
+       This view class should be considered as abstract - it does not implement
+       ``response`` method.
+
+    **View attributes**
+
+    * ``perms``: ``[]``
+    * ``perms_private``: ``['view_project']``
+    * ``perms_GET``: ``[]``
+    * ``perms_POST``: ``[]``
+
+    * ``template_error_name``:  ``projector/project/error.html``
+    * ``template_pending_name``: ``projector/project/pending.html``
+
+    **Required parameters**
+
+    * ``request``: ``django.http.HttpRequest`` instance, which is always passed
+      as first positional argument
+
+    * ``username``:  :model:`Project` would be fetched using this parameter as
+      ``User``'s ``username`` attribute lookup
+
+    * ``project_slug``: :model:`Project` would be fetched using this parameter
+      as :model:`Project`'s ``slug`` attribute lookup
+
+
+    **Context variables**
+
+    * ``project``: :model:`Project` instance fetched using provided parameters
+
+    * ``STATES``: class describing project states (:class:`projector.models.State`)
+
+    * ``project_root``: :model:`Project` instance which is a root in requested
+      project forks tree. If requested project is a root, value of this variable
+      would be same as ``project`` variable.
+
+    * ``forks``: list of :model:`Project` instances which are fork of the
+      requested project. If requested project is a root, list would contain only
+      requested project (would be same as ``project`` variable).
+
+    * ``user_fork``: :model:`Project` instance representing ``request.user``'s
+      own fork of requested project. If user haven't forked this project then
+      ``user_fork`` would be ``None``.
 
     """
 
         return perms
 
     def check_permissions(self):
+        """
+        Checks if user has permissions to call this view. By default, this
+        method would perform checks using requested :model:`Project` instance
+        and permission list retrieved by ``get_required_perms`` method.
+        """
         # Owner's are always allowed to do anything with their projects
         # - this would make less database hits
         if self.project.author == self.request.user:
     We make necessary permission checks *after* dispatching between
     normal and mercurial request, as mercurial requests has it's own
     permission requirements.
+
+    **View attributes**
+
+    * ``template_name``: ``projector/project/detail.html``
+
+    * ``csrf_exempt``: ``True``
+
     """
 
     template_name = 'projector/project/detail.html'
     csrf_exempt = True
 
     def get_required_perms(self):
+        """
+        Returns empty list if request is identified as *mercurial request*.
+        For mercurial requests lets underlying view to manage permissions
+        checks.
+        """
         if is_mercurial(self.request):
-            # For mercurial requests lets undelying view to
-            # manage permissions checking
             return []
         return super(ProjectDetailView, self).get_required_perms()
 
 class ProjectListView(View):
     """
     Project listing view.
+
+    **View attributes**
+
+    * ``template_name``: ``projector/project/list.html``
+
+    **Additional context variables**
+
+    * ``project_list``: :model:`Project` queryset filtered for request's user.
+      Additionally, projects are annotated with :model:`Task` count (available
+      as ``task__count`` attribute on each retrieved project).
+
     """
 
     template_name = 'projector/project/list.html'
 class ProjectCreateView(View):
     """
     New project creation view.
+
+    .. seealso:: :ref:`projects-basics-create`
+
+    **Additional context variables**
+
+    * ``form``: :form:`ProjectCreateForm`
     """
 
     template_name = 'projector/project/create.html'
         she is allowed to create new one.
 
         If user is trying to create more project than specified by
-        MAX_PROJECTS_PER_USER configuration value then we disallow.
+        :setting:`PROJECTOR_MAX_PROJECTS_PER_USER` configuration value then we
+        disallow.
 
-        If request is given, send messages.
+        If request is given, sends messages.
         """
 
         def send_error(request, message):
 class ProjectForkView(ProjectView):
     """
     Project fork (internal fork) view.
+
+    .. seealso:: :ref:`projects-forking`
+
+    **Additional context variables**
+
+    * ``form``: :form:`ProjectForkForm`
+
     """
 
     template_name = 'projector/project/fork.html'
 class ProjectEditView(ProjectView):
     """
     Update project view.
+
+    **Additional context variables**
+
+    * ``form``: :form:`ProjectEditForm`
+
+    * ``form_config``: :form:`ConfigForm`
+
     """
 
     template_name = 'projector/project/edit.html'

projector/views/project_repository.py

 
 
 class RepositoryView(ProjectView):
+    """
+    Base repository view.
+
+    **View attributes**
+
+    * ``perms_private``: ``['view_project', 'can_read_repository']``
+
+    """
 
     perms_private = ['view_project', 'can_read_repository']
 
 
 
 class RepositoryBrowse(RepositoryView):
+    """
+    Repository browsing view.
+
+    In fact, this is only a wrapper for
+    ``vcs.web.simplevcs.views.browse_repository`` view.
+
+    **View attributes**
+
+    * ``template_name``: ``'projector/project/repository/browse.html'``
+
+    **Wrapped view**
+
+       .. autofunction:: vcs.web.simplevcs.views.browse_repository
+
+    """
 
     template_name = 'projector/project/repository/browse.html'
 
 
 
 class RepositoryFileDiff(RepositoryView):
+    """
+    View presenting differences between two file nodes.
+
+    In fact, this is only a wrapper for
+    ``vcs.web.simplevcs.views.browse_repository`` view.
+
+    **View attributes**
+
+    * ``template_name``: ``'projector/project/repository/diff.html'``
+
+    **Wrapped view**
+
+       .. autofunction:: vcs.web.simplevcs.views.diff_file
+
+    """
 
     template_name = 'projector/project/repository/diff.html'
 
 
 class RepositoryFileRaw(RepositoryView):
     """
-    This view returns FileNode from repository as file attachment.
+    This view returns ``FileNode`` from repository as file attachment.
     """
 
     def response(self, request, username, project_slug, revision, rel_repo_url):
         return response
 
 
-class RepositoryFileAnnotate(RepositoryView):
+class RepositoryFileAnnotate(RepositoryBrowse):
+    """
+    View presenting file from repository but with additional annotate
+    information (shows changeset for which each line was added/changed).
+
+    **View attributes**
+
+    * ``template_name``: ``'projector/project/repository/annotate.html'``
+
+    In fact, annotate is done at the template level.
+    """
 
     template_name='projector/project/repository/annotate.html'
 
-    def response(self, request, username, project_slug, revision, rel_repo_url):
-        if self.has_errors:
-            return self.get_error_response()
-        repo_info = {
-                'repository': self.project.repository,
-                'revision': revision,
-                'node_path': rel_repo_url,
-                'template_name': self.template_name,
-                'extra_context': {
-                    'project': self.project,
-                },
-            }
-        return browse_repository(self.request, **repo_info)
-
 
 class RepositoryChangesetList(RepositoryView):
+    """
+    Shows list of changesets for requested project's repository.
+
+    **View attributes**
+
+    * ``template_name``: ``'projector/project/repository/changeset_list.html'``
+
+    **Additional context variables**
+
+    * ``repository``: repository for requested project
+    * ``CHANGESETS_PAGINATE_BY``: number of changesets to be shown at
+      template for each page. Taken from project configuration's
+      ``changesets_paginate_by`` attribute.
+
+    """
 
     template_name = 'projector/project/repository/changeset_list.html'
 
     def response(self, request, username, project_slug):
         if self.has_errors:
             return self.get_error_response()
-        context = {
-            'project': self.project,
-        }
-        context['repository'] = self.project.repository
-        context['CHANGESETS_PAGINATE_BY'] = \
+        self.context['repository'] = self.project.repository
+        self.context['CHANGESETS_PAGINATE_BY'] = \
             self.project.config.changesets_paginate_by
-        return context
+        return self.context
 
 
 class RepositoryChangesetDetail(RepositoryView):
+    """
+    Shows detailed information about requested commit.
+
+    In fact, this is only a wrapper for
+    ``vcs.web.simplevcs.views.diff_changeset`` view.
+
+    **View attributes**
+
+    * ``template_name``: ``'projector/project/repository/changeset_detail.html'``
+
+    **Wrapped view**
+
+       .. autofunction:: vcs.web.simplevcs.views.diff_changeset
+
+    """
 
     template_name = 'projector/project/repository/changeset_detail.html'
 

projector/views/users.py

 
 
 class UserListView(View):
+    """
+    Lists all users.
+
+    **View attributes**
+
+    * ``template_name``: ``projector/accounts/user_list.html``
+
+    **Context variables**
+
+    * ``user_list``: queryset of all users
+
+    """
     template_name = 'projector/accounts/user_list.html'
 
     def response(self, request):
 
 
 class UserHomepageView(View):
+    """
+    Returns user's homepage with some useful data.
+
+    **View attributes**
+
+    * ``template_name``: ``projector/accounts/user_homepage.html``
+
+    **Context variables**
+
+    * ``profile``: user's profile fetched with ``get_profile`` ``User``'s method
+
+    * ``owned_task_list``: queryset of :model:`Task` objects owned by the user
+
+    """
+
     template_name = 'projector/accounts/user_homepage.html'
 
     def response(self, request):
 class UserProfileDetailView(View):
     """
     Public profile of the given user.
+
+    **View attributes**
+
+    * ``template_name``: ``projector/accounts/profile.html``
+
+    **Context attributes**
+
+    * ``profile``: user's profile fetched with ``get_profile`` ``User``'s method
+
+    * ``project_list``: queryset of :model:`Project` objects for which user is
+      member
+
+    * ``groups``: queryset of ``django.contrib.auth.models.Group`` objects for
+      the user if user is converted into a :model:`Team`
+
     """
     template_name = 'projector/accounts/profile.html'
 
 
 class UserDashboardView(View):
     """
-    Edit profile view.
+    User's dashboard panel.
+
+    **View attributes**
+
+    * ``template_name``: ``projector/accounts/dashboard.html``
+
+    **Context variables**
+
+    * ``form``: :form:`UserProfileForm` with current user's profile instance
+
+    * ``profile``: profile passed as instance into the form
+
+    * ``site``: current ``Site`` object
+
+    * ``can_fork_external``: boolean allowing or disallowing user to fork
+      projects from external locations
+
     """
 
     template_name = 'projector/accounts/dashboard.html'
 
 class UserDashboardForkView(View):
     """
-    Fork external project view.
+    Returns :form:`ExternalForkWizard` which encapsulates logic for external
+    forks.
+
+    .. seealso:: :ref:`projects-forking-external`
+
+    **View attributes**
+
+    * ``template_name``: ``projector/accounts/dashboard_fork.html``
+
+    * ``login_required``: ``True``
+
     """
 
     template_name = 'projector/accounts/dashboard_fork.html'
 
 class UserDashboardConvert2TeamView(View):
     """
-    Convert to team view.
+    Converts user into :model:`Team`.
+
+    .. seealso:: :ref:`teamwork-membership-convert`
+
+    **View attributes**
+
+    * ``template_name``: ``projector/accounts/dashboard-convert-confirm.html``
+
+    **Context variables**
+
+    * ``form``: :form:`UserConvertToTeamForm`
+
+    * ``profile``: user's profile retrieved using ``User``'s ``get_profile``
+      method
+
     """
 
     template_name = 'projector/accounts/dashboard-convert-confirm.html'
 
 class UserDashboardAddMember(View):
     """
-    Add new member view.
+    Adds new member. Only applicable for :model:`Team`.
     """
 
     template_name = 'projector/accounts/dashboard-add-new-member.html'
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.