add Sphinx version information markups

[fero14041]

Sphinx introduces some paragraph-level markups related to versions informations in documentation, i.e. "{{{.. versionadded::}}}", "{{{.. versionchanged::}}}" and "{{{.. deprecated::}}}". It should be convenient for users if SQLAlchemy uses these markups.

Some patches are already created, and publicly available on a bitbucket repository. They apply on top of current (at time of writing) SQLAlchemy repo tip, but on default branch only.

Patches usage (as remainder)

Patches are managed as a Mercurial Queue, and should be stored (files or repository) in {{{.hg/patches}}}.

In SQLAlchemy repo:

# go (or rest) in default branch
hg update default
# select MQ guard for this branch
hg qselect default_branch

# add CSS styles
hg qpush
# change styles if needed
# (...)
# save changes by refreshing patch
hg qrefresh

# review subsequent patch
hg qpush
# change patch modifications if needed
# (...)
# save changes
hg qrefresh

# and so on for patches guarded for this branch

[fero14041]

I'll try to port patches already done from default branch to others, in this week-end (from Saturday 19 to Sunday 20/5/2012). Also, these patches ''need'' IMHO a review, as I'm a complete newbee with SQLAlchemy: they may introduce some non-sense or wrong content.

[Mike Bayer]

OK great, thanks so much for taking this on ! it's very hard to get help with the docs. I'll put this on 0.7.8 and try to review soon (just starting a long day here...)

[fero14041]

Ok, I think I'm done with those patches, but they need a serious review, as introduced changes:

• may be wrong (as I had not yet start reading full documentation), especially when rewriting phrases;
• may be irrelevant (in some cases, it was not clear for me to use one markup or the other; on one case a paragraph-level markup is included ''inside'' a {{{.. note::}}});
• may be incomplete (in some case, I can't find appropriate markup or rewriting);
• may be "typoed" (I didn't check if ''each'' change is well transformed in HTML).

Moreover, version infos markups only accept two arguments, the version and an optional and ''alone'' paragraph. Sometimes, it would be preferable to have more than one paragraph marked, for example when some code sample is attached. Code included in such marked paragraphs must be in an inlined reST litteral, instead of a plain {{{.. code-block::}}}. There is a trade-off between showing code with highlighting it or put accent in version number change... and in first case a plain old {{{.. note::}}} would be better.

Anyway, a result of patches applied could be seen/reviewed in a public repository. I had also include a short README, as my personal remainder (enhancing previous part in ticket description), on how use these patches.

[Mike Bayer]

they look great so far. I guess I have to learn MQ first to really do this. I'll let you know how that goes.

[fero14041]

Oh, I suppose that the README could suffice -- or perhaps it is not clear enough? Otherwise you could simply pull changes from the repository, and review/make changes over result. (Of course, you loose the possibility to change patches before permanently add them to the history.)

[Mike Bayer]

i need to do the MQ because I did see some things that need adjustment and doing it straight on the patch seems easiest.

[Mike Bayer]

question: is syntax like this something standard? i.e. the version numbers in a {} like that.

Changed in version 0.6.{2,3,4}: @declared_attr is available as sqlalchemy.util.classproperty for SQLAlchemy versions 0.6.2, 0.6.3, 0.6.4

[fero14041]

I don't think so. But the {{{.. versionchanged::}}} markup accepts only two arguments: (i) the version concerned, and (ii) a description explaining changes, separated by a space or a line break. So in this case concerned by multiple versions, I didn't found anything other than this pretty ugly notation, agglomerated them in this non-spaced syntax. Any other idea could be better...

[Mike Bayer]

the changes look great, and I'm not seeing what it was earlier I wanted to fix. I think in some cases, where we have something like "The XYZ does QPR (new in 0.6)", and that's inside a "..versionchanged" directive, the "XYZ does QPR" is part of the primary behavior we want to describe, so at some point some of those may change to read "The XYZ does QPR. ..versionchanged:: 0.6 XYZ now does QPR".

Since I'm more concerned about the repository falling behind these changes rather than I am about finding small issues, I'm pushing the whole lot in. However, I'm at a conference where the wifi is not terribly quick, this might take a bit. I'll post the rev ids here and hit rebuild on readtehdocs once I can get the data over the wire.

[Mike Bayer]

hm OK :

97e97324d67056972b1f959ce41d0be441cec992 27f7c595d216c8b1d87e5a3648ada09f684542d9 d8d080a76913af5d192c5ef627b8453c05d0e2c8 0c1bc8b54d819c13b55e32ed8f808738469baa18 d95ef256d0c634edbe292b3ca2b3b2a0e6b05a5f c8e847811fcff2beb0244ec33016898da0e0ec89 4d7330f9b7f5a2800ff1d799ca40dd605b7348eb ce7aab4530168820cbac6b84f8fb01c8d72776e6 38cb8b367bfb8b6b4e70503a91af6c63c7e39b1a bc0287cc9612e9b0e654433541457c3032df9ce7 ee7c5bf159e7a0650ec2b1b6c8d7d8d0434b27a9 a34590e03c8bf3f380cf0b115d53e180a1e409b7

thanks for the tremendous amount of work here !

[fero14041]

Yes, thanks for pushing patches! Please let excuse this late answer, I probably was in an other space this past week... Next time I'll purpose big patches, I will just point you non-trivial changes {{{^_^;)}}}.

[Mike Bayer]

Removing milestone: 0.7.8 (automated comment)