Re: Doc building piece missing?

2009-11-21 Thread Russell Keith-Magee 
On Sun, Nov 22, 2009 at 5:17 AM, Tim Chase
 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 %-)

--

You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To post to this group, send email to django-develop...@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=.

Re: Doc building piece missing?

2009-11-21 Thread Russell Keith-Magee 
On Sat, Nov 21, 2009 at 9:59 PM, Luke Plant  wrote:
> On Saturday 21 November 2009 11:54:40 Tim Chase wrote:
> 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.

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 %-)

--

You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To post to this group, send email to django-develop...@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=.

Re: Doc building piece missing?

2009-11-21 Thread 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/

--

You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To post to this group, send email to django-develop...@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=.

Doc building piece missing?

2009-11-21 Thread 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


--

You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To post to this group, send email to django-develop...@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=.