On 25-01-2014, Steve Piercy wrote: > 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.
Where is this advise against pip ? (easy_install pyramid alone will install 1.5 also isn'it ?) > > (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. Yes > > (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. Of course, i try... https://github.com/flibustenet/pylonsrtd/tree/separate_latest_master -- William -- 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.
