get some pep-257 goodness into the docs

[Mike Bayer]

at the very least, get each docstring to have the one line "command" sentence at the beginning (i have been 100% using a non-command verb ....), and put spaces between the argument descriptions so the documentation parser stuff has an easier job:

def whatsit(x, y):
    """perform the whatsit and return the green eggs and ham.

    this method does a lot of crap. here is where we describe
    the crap, in a paragraph with newlines to keep it wihtin
    a small number of columns.

    x - the x value.

    y - the y value. blah blah blha about the y value and
    some more blah blah about the y value, notice the newlines
    within the description of 'y', thats why theres a blank
    line between the 'x' description and the 'y' description,
    to differentiate between "new paragraph" and "discardable newline".

    returns the green eggs and ham, which are lightly poached on an
    english muffin.

    the closing triple quotes is on a line by itself.
    """

[Former user]

I'd like to contribute some time on this. I'd be even more happy to reformat the docstrings into a somewhat stricter reStructuredText, properly using {{{identifiers}}} and {{{code sample}}} quoting, and maybe definition lists for keyword arguments...

I'd like to bring also some PEP8 fixes, for example uniformely using a single empty line between methods.

What do you think?

[Mike Bayer]

OK! if you are going to restructure the code examples and such we might want to look into getting my little docstring HTML formatter to handle it too.

it might be nice if you want to do a couple of files first, so i can get a feel for what the total change is going to look like.

[Former user]

Sample of intended changes: sqlalchemy/engine

[Former user]

Let me know if you prefer an even stricter PEP8 adherence; it recommends using two blank lines between major objects, and to leave the triple quotes on a line by their own, that is:

def function(arg):
    """
    This does that.

    Longer explanation.
    """

    return arg*2

[Mike Bayer]

it looks terrific; i wouldnt worry about the two blank lines.

we need to tweak the formatting in doc/build/components/pydoc.myt , i guess to not try to reformat the docstrings as much since the formatting is good as is now.

so...should i commit that patch or should we wait til patches are available for most docs ?

thanks so much for this one its a lot of work !

[Former user]

The complete work

[Former user]

I almost completed the task, touching all the sources with the notable exception of sqlalchemy/database/, for which I'd like to have an explicit "go", since the various backend are written by several people, with different styles.

Please, let me know if you prefer to apply it in smaller chunks.

[Former user]

New patch, that touches also the database/ stuff (ie, everything except tests/)

[Mike Bayer]

Ok ive applied the patch in changeset:2363. not all the hunks succeeded in the patch despite repeated attempts to revert recent changes, do the patches in reverse direction,etc. i can attach the failed hunks if you want.

[Former user]

Great, thank you Michael! I'll try first to resync my working copy and let you know.

If needed, I'll keep an eye on forthcoming commits and add new patches here. Maybe we should explicitly document the preferred style on the SA wiki, like trac itself does in its CodingStyle page. If you think that's reasonable, I'll adapt that page to SA.

[Former user]

Remaining bits, related to rejected hunks

[Mike Bayer]

update, ive merged the mako doc generation in changeset:2419. i then read the docutils info and implemented docutils formatting, plus several dozen reST fixes across the docstrings which it was reporting, in changeset:2420. so those latest docutils-generated docs are on the site now.

[Mike Bayer]

commited in changeset:2451 the latest patch, not much of it took....sorry.

[Former user]

Michael, no problem at all: please let me know which kind of changes you didn't like, if that's case. I'll be happily keep this alive, if you agree. I'm going to attach a new diff against current trunk.

[Former user]

Ouch, spurious change slipped in

[Mike Bayer]

great. the whole thing went in in changeset:2478

[Mike Bayer]

i think we're pretty peppy at this point, save for the occasional long intro sentence...not sure what can be done about some of those. regular doc cleanups and further work to add "live" doc tokens, supported by SQLAlchemy's docstring framework, are ongoing.

[Mike Bayer]

Removing milestone: 0.4.0 (automated comment)