On 1/25/14 at 2:05 PM, [email protected] (wilk) pronounced:
On 24-01-2014, Thomas Grzybowski wrote:
------=_Part_815_30592099.1390600126697
Content-Type: text/plain; charset=UTF-8
Oh - I did not know that we had 1-5-branch tutorials, a
mistake. I will take your advice and start clean again using
the up-to-date tutorial.
Thanks,
Tom
I don't see the main page of documentation very clear also.
When we install with pip install pyramid the v 1.5a come, then
on the main page if we don't read to the end of each line we see
latest
pyramid 1.5
pyramid 1.4
...
pyramid dev
So we click on latest...
I think stable and dev could be more clear on this page, like
with the stamp "risky". Maybe even with a little warning : if
you installed with pip you will have this one.
For example with 1.5/dev on an other chapter. Or with an explicit 'a': 1.5a...
(1) The documentation always states use easy_install or
distribute, and usually either omits pip or advises against its use.
(2) The naming convention of documentation is a little clumsy,
but that's a RTD "feature".
https://docs.readthedocs.org/en/latest/canonical.html?highlight=latest
Pyramid docs have numbered branches (1.5-branch, 1.4-branch,
etc.) and a branch named "master".
The canonical URL of the docs is mapped to the stable release,
currently 1.4-branch, which has the URL slug "latest". It's an
arbitrary label, and I would call it misleading. Personally I
think it should be labeled "stable", and I would lobby the
wonderful folks at RTD to change that convention.
The URL for the "master" branch always maps to the development,
and most current, branch of the docs, currently "1.5-branch".
Note that English typically defines "latest" as "most current",
whereas RTD defines "latest" as "stable release". This is where
much of the confusion arises.
To summarize, as of today:
"latest" = "1.4-branch" = stable release
"master" = "1.5-branch" = development release
When development of the next release of Pyramid starts, then it
will shift:
"latest" = "1.5-branch" = stable release
"master" = "1.6-branch" = development release
(3) I don't know what you mean by "main page". URLs are
better, and remove ambiguity. However, I think you mean this:
http://docs.pylonsproject.org/en/latest/docs/pyramid.html#main-documentation
wherein we have attempted to summarize what happens in (2) above.
(4) Finally, and most importantly, if you complain about the
docs, then you should submit a pull request and do something
about it. Help improve the docs to make them clearer.
--steve
------------------------
Steve Piercy, Soquel, CA
--
You received this message because you are subscribed to the Google Groups
"pylons-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/pylons-discuss.
For more options, visit https://groups.google.com/groups/opt_out.
