"New in development version" equivalent in current docs?
Malcolm Tredinnick
was new gave me a bit of a headache. I ended up adding
.. versionadded:: development
which is a pretty digusting hack. Sphinx really wants
.. versionadded:: X.Y
You can't put anything with spaces in there. It feels a little
inconsistent to put 1.1 in there, since we generally hold off talking
about version numbers from the future so that bug reporters are forced
to use accurate version numbers.
So there seem to be two choices. Well, three if you permit the current
hack, but I don't really like it, since it doesn't work with "make
changes". The first option is use ".. versionadded:: 1.1". The second
option is to write our own directive that goes back to the old "New in
Django development version".
I'd probably say that we bite the bullet and use 1.1 except then we
should do what one of the Spanish Marc's has suggested in a ticket
somewhere (could I be any less specific on the details, do you think?)
and make the main documentation link point to the 1.0 docs and put a
"development docs this way" sign up somewhere.
Thoughts?
Regards,
Malcolm
Russell Keith-Magee
<mal...@pointy-stick.com> wrote:
>
> I'd probably say that we bite the bullet and use 1.1 except then we
> should do what one of the Spanish Marc's has suggested in a ticket
> somewhere (could I be any less specific on the details, do you think?)
> and make the main documentation link point to the 1.0 docs and put a
> "development docs this way" sign up somewhere.
>
> Thoughts?
+1 to Marc's suggestion regarding the main documentation link being
the v1.0 docs.
I'm still coming to grips with Sphinx, but is there any reason that we
can't just use 1.X or 1.SVN as a version number for the development
version? That gets around the need to specify the exact version
number, but keeps it reasonably obvious that it's a development
version.
Russ %-)
Karen Tracey
I'd probably say that we bite the bullet and use 1.1 except then we
should do what one of the Spanish Marc's has suggested in a ticket
somewhere (could I be any less specific on the details, do you think?)
and make the main documentation link point to the 1.0 docs and put a
"development docs this way" sign up somewhere.
Maybe you mean ticket #8992: http://code.djangoproject.com/ticket/8992?
I'm not wild about the idea of making the older docs the default, I've always rather liked seeing what's new and improved in the default, but don't feel that strongly about it. I do think if we switch to "latest official release" as the default it would be better to use the 1.0.X branch content rather than the 1.0 release tag content.
Karen
Tim Chase
> can't just use 1.X or 1.SVN as a version number for the development
> version? That gets around the need to specify the exact version
> number, but keeps it reasonably obvious that it's a development
> version.
If non-digits are allowed, one might even consider something like
trunk.8123
to indicate that the documentation was added for a feature in
trunk, r8123 which would help pair documentation with code
sitting on a developer's machine.
Possible problems (having not tinkered with Sphinx enough to know
how it works) include:
1) balking at non-digits in a version number
2) if Sphinx builds documentation for each revision it finds, one
might end up with myriad documentation folders, one for each SVN
revision in the docs.
Just my $0.02 (though in the current economy, that's pretty
expensive, but still won't buy you much gasoline ;-)
-tim
Malcolm Tredinnick
On Tue, 2008-10-07 at 07:38 -0500, Tim Chase wrote:
> > I'm still coming to grips with Sphinx, but is there any reason that we
> > can't just use 1.X or 1.SVN as a version number for the development
> > version? That gets around the need to specify the exact version
> > number, but keeps it reasonably obvious that it's a development
> > version.
>
> If non-digits are allowed, one might even consider something like
>
> trunk.8123
>
> to indicate that the documentation was added for a feature in
> trunk, r8123 which would help pair documentation with code
> sitting on a developer's machine.
Please, no. The idea isn't to create even more work for us. :-)
This would mean we can't commit correct documentation with the change
that introduces a feature (since one needs to know the revision number)
and you end up having to always remember to make a second commit. If a
developer is tracking trunk they can keep up to speed themselves. If
they can't, there's a 1.0.X branch there for their very own personal
use.
Regards,
Malcolm
Marc Fargas
On Tue, Oct 7, 2008 at 1:17 PM, Malcolm Tredinnick
<mal...@pointy-stick.com> wrote:
> You can't put anything with spaces in there. It feels a little
> inconsistent to put 1.1 in there, since we generally hold off talking
> about version numbers from the future so that bug reporters are forced
> to use accurate version numbers.
>
> I'd probably say that we bite the bullet and use 1.1 except then we
> should do what one of the Spanish Marc's has suggested in a ticket
> somewhere (could I be any less specific on the details, do you think?)
> and make the main documentation link point to the 1.0 docs and put a
> "development docs this way" sign up somewhere.
That's me! There are two consecutive tickets that talk about
version[added|changed]. You may be talking about #8992 and there's
also #8991 (about when to remove those strings :P)
From my POV, when you commit something to trunk you know it's going to
be in the next X.Y release, so it's safe to put the X.Y version
"to-be-released-next". I don't really think people need to know in
which exact moment of the development process the feature went in (if
you are tracking trunk, you *track* it).
*Maybe* we could instruct Sphinx in ways to change the X.Y thing
"automagically" to "Development Version" when X.Y refers to the
yet-to-be-released version. But writting there anything that is not
the X.Y of the next version means more work *before release* (change
whatever was there to the corresponding X.Y).
Just my 0.02,
Marc