Epydocs style Docstrings in Python (ReStructuredText)

http://pygments.org/demo/15101/


Sample Django Model With Epydoc style comments

from django.db import models
from django.contrib.auth.models import User 

# Create your models here.
# Example documentation for pydoc included
class gus_user(models.Model):
    """
    class gus_user model is our model of a user of the gus system
    
    it shall encompass all of the data and 
    all of the discreet functionality of users of the gus system    
    """
    
    #Our Fields
        #Django recommends using OneToOne Fields to extend built in models
    #our key is remote record of builtin django.User
    # double underscores signifies private variables (sort of)
    __user = models.OneToOneField(User, primary_key=True)  
    bio = models.TextField()    # Sample Extension Field

                                               
    #################################################
    ####  Python Magic Functions       ##############
    #################################################
                                                
    #define how to display our object in the html
    def __unicode__(self):
        """
        This defines the default display of a user
        for now we will just return the default django.User display
        
        @rtype:   string
        @return:  the default string for built in django.User.
        """
        
        return "User: %s" % self.user or '(Not Defined)'
     
    
    
    ################################################
    ###   Getters And Setters ######################
    ################################################
    #Define our setters , syntax is:def setProperty(self): ... 
    #    s.t. Property is the name of the property you wish to use 
    #  a setter for , with the first letter capitalized
    
    #setter for our user
    def setUser(self,user):
        """
        Set our user
        
        @type user:django.contrib.auth.models.User
        @param user: the user to parent to this instance
        @rtype: none 
        """
        self.__user=user
        
    #setter for our username
    def setUsername(self,value):
        """
        Set our user.username
        
        @type  m: string
        @param m: the new username.
        @rtype: none
        """
        self.__user.username=value
        
    
    #Define our getters , syntax is:def getProperty(self): ... 
    #    s.t. Property is the name of the property you wish to use
    #  a getter for, with the first letter capitalized
    
    #getter for our username
    def getUsername(self):
        """
        Return our user.username
        
        @rtype: string
        @return: the value of our parent user's username
        """
        return self.__user.username
    
    #getter for our user
    def getUser(self):
        """
        Return our user
        
        @rtype: django.contrib.auth.models.User
        @return: the value of our parent user
        """
        return self.__user
    
    
    #GETTER/SETTER enabled ... hackish
    #GETTERS AND SETTERS WILL BE USED (!Include simillar code in all classes)
    #getter and setter hooks , these must be setup if you wish to 
    #use gus_user.<property> = <blah>  or print gus_user.<property>
    # A Hack to make variables use setter
    
    #user hook
    user = property(getUser,setUser)
    
    #username hook
    username = property(getUsername,setUsername)

http://www.slideshare.net/pydanny/python-worst-practices

http://stackoverflow.com/questions/9210446/replace-local-branch-with-remote-branch-entirely