Doc building piece missing?

[Tim Chase]

Just noticed this in [1]

--------------------------------------
csrf_token�

New in Django 1.1.2:

System Message: WARNING/2
(/home/djangodocs/en/dev/ref/templates/builtins.txt)

undefined label: releases-1.1.2
--------------------------------------


Looks like some tag/label needs to be created for the doc build
process to find it. If this needs a bug report to be filed, I
can do that too, but it may just be a fast "whoops" fix. I'm
guessing it's not the only instance in the docs, but I'd also
guess that the same fix should solve all of them.

[1]
http://docs.djangoproject.com/en/dev/ref/templates/builtins/#csrf-token

-tim

[Luke Plant]

On Saturday 21 November 2009 11:54:40 Tim Chase wrote:
> Just noticed this in [1]
>
> --------------------------------------

> csrf_tokenś

>
> New in Django 1.1.2:
>
> System Message: WARNING/2
> (/home/djangodocs/en/dev/ref/templates/builtins.txt)
>
> undefined label: releases-1.1.2
> --------------------------------------
>
>
> Looks like some tag/label needs to be created for the doc build
> process to find it. If this needs a bug report to be filed, I
> can do that too, but it may just be a fast "whoops" fix. I'm
> guessing it's not the only instance in the docs, but I'd also
> guess that the same fix should solve all of them.

It is supposed to be 1.1.2, and at the moment it is the only instance
in the docs. The circumstances which created the need for this are
rare — we added a new 'feature' to the 1.1 branch, which in reality is
a no-op, but will help to ease the transition from the 1.1.X branch to
the 1.2.X branch.

There is a comment on this bug:

http://code.djangoproject.com/ticket/12130#comment:6

The problem is there are no 1.1.2 release notes yet. Also, if you put
"versionchanged:: 1.2", our docs are set up to parse that as referring
to the next version of Django, so it says "Development version". The
same isn't true of 1.1.2. I don't know how this should be handled.

Perhaps the easiest way is to start the tentative 1.1.2 release notes
as has been done with the 1.2 notes.

Luke

--
"DO NOT DISTURB. I'm disturbed enough already."

Luke Plant || http://lukeplant.me.uk/

[Russell Keith-Magee]

This would be a break in tradition. We don't (or haven't in the past)
done release notes for point releases, as they are normally only
bugfixes and/or security updates.

I can see three possiblities here:

1. Mark the feature as 'versionadded:1.2" in trunk; in the 1.1.X
branch, mark it 'versionadded:1.1', but with an explanatory note
clarifying that strictly, it's 1.1.2.

2. Mess around with the Sphinx processor and make it display point
release numbers but link to the minor release.

3. Actually create a 1.1.2 release notes document, whose sole purpose
is to document this extraordinary feature.

I don't have any preference on the color of this particular bikeshed.
If pressed, I'd probably say option 3.

Regarding the issue of whether this is the only reference failure in
the docs - there is actually one other; the 1.2 release notes aren't
listed in the release notes index file.

Yours,
Russ Magee %-)

[Tim Chase]

> This would be a break in tradition. We don't (or haven't in the past)
> done release notes for point releases, as they are normally only
> bugfixes and/or security updates.
>
> I can see three possiblities here:
>
> 1. Mark the feature as 'versionadded:1.2" in trunk; in the 1.1.X
> branch, mark it 'versionadded:1.1', but with an explanatory note
> clarifying that strictly, it's 1.1.2.

A bit hackish, but passable.

> 2. Mess around with the Sphinx processor and make it display point
> release numbers but link to the minor release.

A big -1 if documentation can only be built with a custom version
of Sphinx, making it harder for others to build docs. A -0 if
it's something in stock Sphinx that can be twiddled via
configuration/setup.

> 3. Actually create a 1.1.2 release notes document, whose sole purpose
> is to document this extraordinary feature.
>
> I don't have any preference on the color of this particular bikeshed.
> If pressed, I'd probably say option 3.

As Luke said, "the circumstances which created the need for this
are rare", so #3 sounds like the right way to handle it -- an
anomalous trigger gets an anomalous "break in tradition"... It
also sounds like what first came to Luke's mind as a solution,
making it three minds agreeing with no dissenting suggestions.

-tim

[Russell Keith-Magee]

On Sun, Nov 22, 2009 at 5:17 AM, Tim Chase
<django...@tim.thechases.com> wrote:
>>  2. Mess around with the Sphinx processor and make it display point
>> release numbers but link to the minor release.
>
> A big -1 if documentation can only be built with a custom version
> of Sphinx, making it harder for others to build docs. A -0 if
> it's something in stock Sphinx that can be twiddled via
> configuration/setup.

It sounds like there's a vague consensus around option 3 (having 1.1.2
release notes), but for the record - option 2 doesn't mean a custom
compiled version of Sphinx. Sphinx allows you to add custom tags and
processing instructions (see docs/_ext/djangodocs.py). Django uses
these to provide most of the useful cross references and version
tagging in the docs, including versionadded.

Yours,
Russ Magee %-)