Added docstrings to most of the important modules, and included a few more modules in the api .rst files

Author: wapcaplet

bookmarks/admin.py

@@ -1,3 +1,6 @@
+"""Django admin interface for `~bookmarks.models.Bookmark`.
+"""
+
 from django.contrib import admin
 from bookmarks.models import Bookmark
 

bookmarks/views.py

@@ -17,27 +17,34 @@ def bookmark_list(request, queryset=Bookmark.objects.all()):
 
 @login_required
 def user_bookmark_list(request):
+    """Show a list of the current user's bookmarks.
+    """
     queryset = Bookmark.objects.all()
     queryset = queryset.filter(user=request.user)
     return bookmark_list(request, queryset=queryset)
 
 @login_required
 def bookmark_add(request, url):
+    """Add a new bookmark for the current user to ``url``.
+    """
     bookmark, _ = Bookmark.objects.get_or_create(user=request.user, url=url)
-    
+
     payload = simplejson.dumps({'added': True})
-    
+
     return HttpResponse(payload, mimetype='text/javascript')
 
 @login_required
 def bookmark_remove(request, url):
+    """Remove the current user's bookmark to ``url``.
+    """
     try:
         bookmark = Bookmark.objects.get(user=request.user, url=url)
     except Bookmark.DoesNotExist:
         pass
     else:
         bookmark.delete()
-    
+
     payload = simplejson.dumps({'removed': True})
-    
+
     return HttpResponse(payload, mimetype='text/javascript')
+

builds/admin.py

@@ -1,3 +1,6 @@
+"""Django admin interface for `~builds.models.Build` and related models.
+"""
+
 from django.contrib import admin
 from builds.models import Build
 

builds/views.py

@@ -9,6 +9,8 @@
 from taggit.models import Tag
 
 def build_list(request, username=None, project_slug=None, tag=None):
+    """Show a list of builds.
+    """
     queryset = Build.objects.all()
     if username:
         user = get_object_or_404(User, username=username)
@@ -35,7 +37,10 @@ def build_list(request, username=None, project_slug=None, tag=None):
         template_object_name='build',
     )
 
+
 def build_detail(request, username, project_slug, pk):
+    """Show the details of a particular build.
+    """
     user = get_object_or_404(User, username=username)
     queryset = Build.objects.all()
 
@@ -52,3 +57,4 @@ def build_detail(request, username, project_slug, pk):
         extra_context={'user': user, 'project': project },
         template_object_name='build',
     )
+

core/admin.py

@@ -1,3 +1,6 @@
+"""Django admin interface for core models.
+"""
+
 from django.contrib import admin
 
 from core.models import UserProfile

core/management/commands/update_repos.py

@@ -3,7 +3,9 @@
 from projects.models import Project
 
 class Command(BaseCommand):
-
+    """Custom management command to rebuild documentation for all projects on
+    the site. Invoked via ``./manage.py update_repos``.
+    """
     def handle(self, *args, **kwargs):
         if not len(args):
             tasks.update_docs_pull()

core/views.py

@@ -1,3 +1,7 @@
+"""Core views, including the main homepage, post-commit build hook,
+documentation and header rendering, and server errors.
+"""
+
 from django.conf import settings
 from django.db.models import F, Max
 from django.http import HttpResponse, HttpResponseRedirect
@@ -58,7 +62,7 @@ def serve_docs(request, username, project_slug, filename):
     The way that we're serving the documentation.
 
     This is coming out of Django so that we can do simple page counting, and
-    because later we can use Django auth to protect views. 
+    because later we can use Django auth to protect views.
 
     This could probably be refactored to serve out of nginx if we have more
     time.

docs/api/core.rst

@@ -31,3 +31,14 @@
 .. automodule:: core.views
     :members:
 
+
+:mod:`core.management.commands`
+----------------------------------
+This is where custom ``manage.py`` commands are defined.
+
+.. automodule:: core.management.commands.build_files
+    :members:
+
+.. automodule:: core.management.commands.update_repos
+    :members:
+

docs/api/index.rst

@@ -1,6 +1,9 @@
 API
 ===
 
+This is the Read The Docs API documentation, autogenerated from the source
+code.
+
 .. toctree::
 
     bookmarks

docs/api/projects.rst

@@ -36,3 +36,16 @@
 .. automodule:: projects.utils
     :members:
 
+:mod:`projects.views`
+----------------------------------
+
+:mod:`projects.views.public`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodule:: projects.views.public
+    :members:
+
+:mod:`projects.views.private`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodule:: projects.views.private
+    :members:
+

projects/admin.py

@@ -1,3 +1,7 @@
+"""Django administration interface for `~projects.models.Project`
+and related models.
+"""
+
 from django.contrib import admin
 
 from projects.models import Project, File, ImportedFile

projects/constants.py

@@ -1,3 +1,7 @@
+"""Default values and other various configuration for projects,
+including available theme names and repository types.
+"""
+
 THEME_DEFAULT = 'default'
 THEME_SPHINX = 'sphinxdoc'
 THEME_SCROLLS = 'scrolls'

projects/tasks.py

@@ -1,3 +1,7 @@
+"""Tasks related to projects, including fetching repository code, cleaning
+``conf.py`` files, and rebuilding documentation.
+"""
+
 from celery.decorators import task
 from celery.task.schedules import crontab
 from celery.decorators import periodic_task
@@ -21,6 +25,7 @@ class ProjectImportError (Exception):
     """Failure to import a project from a repository."""
     pass
 
+
 @task
 def update_docs(pk, record=True):
     """
@@ -119,6 +124,9 @@ def update_imported_docs(project):
 
 
 def scrape_conf_file(project):
+    """Locate the given project's ``conf.py`` file and extract important
+    settings, including copyright, theme, source suffix and version.
+    """
     try:
         conf_dir = project.find('conf.py')[0]
     except IndexError:
@@ -200,8 +208,11 @@ def fileify(project_slug):
                     file, new = ImportedFile.objects.get_or_create(project=project,
                                                 path=dirpath,
                                                 name=filename)
+
+
 @periodic_task(run_every=crontab(hour="*", minute="10", day_of_week="*"))
 def update_docs_pull():
     for project in Project.objects.live():
         print "Building %s" % project
         update_docs(pk=project.pk, record=False)
+

projects/utils.py

@@ -1,3 +1,6 @@
+"""Utility functions used by projects.
+"""
+
 import subprocess
 import os
 import fnmatch
@@ -8,13 +11,18 @@
 
 from projects.libs.diff_match_patch import diff_match_patch
 
+
 def find_file(file):
+    """Find matching filenames in the current directory and its subdirectories,
+    and return a list of matching filenames.
+    """
     matches = []
     for root, dirnames, filenames in os.walk('.'):
       for filename in fnmatch.filter(filenames, file):
           matches.append(os.path.join(root, filename))
     return matches
 
+
 def run(*commands):
     """
     Run one or more commands, and return ``(status, out, err)``.
@@ -58,14 +66,20 @@ def diff(txt1, txt2):
     patch = dmp.patch_make(txt1, txt2)
     return dmp.patch_toText(patch)
 
+
 def safe_write(filename, contents):
+    """Write ``contents`` to the given ``filename``. If the filename's
+    directory does not exist, it is created. Contents are written as UTF-8,
+    ignoring any characters that cannot be encoded as UTF-8.
+    """
     dirname = os.path.dirname(filename)
     if not os.path.exists(dirname):
         os.makedirs(dirname)
     fh = open(filename, 'w')
     fh.write(contents.encode('utf-8', 'ignore'))
     fh.close()
 
+
 def sanitize_conf(conf_filename):
     """Modify the given ``conf.py`` file from a whitelisted project. For now,
     this just adds the RTD template directory to ``templates_path``.
@@ -93,3 +107,4 @@ def sanitize_conf(conf_filename):
         outfile.write(line)
     outfile.close()
     return lines_matched
+

watching/admin.py

@@ -1,3 +1,6 @@
+"""Django admin interface for `~watching.models.PageView`.
+"""
+
 from watching.models import PageView
 from django.contrib import admin