How to document a Django project?

Question

How should I go about documenting a Django project? I'm not talking about an app that I'm creating that I'll push to github. It's basically internal documentation that will help new developers that we employ to get up to speed with the system. (I guess that's the point of documentation in general)

Should I be documenting each and every view function, model or form as below:

def home(request):
    """View that renders the home page."""

class MyModel(models.Model):
    "Documentation regarding my model."""

It seems like a bit of overkill. Are there perhaps some good projects that I can look at for inspiration?

Answer 1

An effective way to document code and open it up to understanding by new devs in my experience is literate programming.

https://en.wikipedia.org/wiki/Literate_programming

The main thing is that there's a narrative that really explains what's going on, rather than a set of loose remarks.

I prefer a somewhat non-standard form of literate programming, where I put my comments behind the code, rather than in between it. Experienced devs won't be hindered by it in this way.

So like:

class Node (object):                                    # Node representing atomary partial state in a state machine
    def __init__ (self, value = Nothing):               # Initial value is optional, not needed in case of dependent nodes ('Nothing' introduced y15m02d14)
        self.sinkNodes = []                             # Nodes that depend on this node
        self.links = []                                 # Zero or more links to bareRead / bareWrite pairs
        self.exceptions = []
        self.actions = []
        self.validator = lambda value: True             # Validators are deprecated, use exceptions instead

        self.persistent = False                         # Assume not worth persisting
        self.recursionCount = 0

        if value ==  Nothing:                           # If node is uninitialized
            self.event = 0                              #   It should be updated
        else:                                           # If node is supposed to be freely initialized
            self.currentValue = value                   #   Free initialisation
            self.previousValue = self.currentValue      #   Make sure previousValue is available in case of free initialisation
            self.event = currentEvent ()                #   Remember up to date

            if not value is None:                       #   If it is a freely initialized ordinary node rather than an event-only node
                self.persistent = True                  #       Remember it is part of a non-redundant basis for persistence


(etc.)

On the other hand blindly placing an obvious remark at each class and function and then generating doc with a tool hasn't helped me much in understanding anything. I need to have the actual code at hand, which is the case here.

At truly difficult points in your code it doesn't hurt to have an explanation block over the full width.

'''
As soon as we encounter a module in the chain that isn't already there, we'll have to create the remainder (tail) of the chain.

    e.g.
        import a.b.c.d.e
        import a.b.c

    will generate
        modules = {}
        __nest__ (a, 'b.c.d.e', __init__ (__world__.a.b.c.d.e))
        __nest__ (a, 'b.c', __init__ (__world__.a.b.c))

    The task of the __nest__ function is to start at the head object and then walk to the chain of objects behind it (tail),
    creating the ones that do not exist already, and insert the necessary module reference attributes into them.
'''

def __nest__ (headObject, tailNames, value):
    current = headObject

(etc.)