Minor documentation issue: wrong "latest" version on readthedocs

[lmctv]

As of now, if I follow the default link to colander docs,
http://colander.readthedocs.org/, I land on the docs for v 1.0b1 since the default version "latest" points to "1.0-branch".

[stevepiercy]

It looks like there is some missing meta documentation for the project.

First we need to determine which branch should be "latest". We don't have a 1.1-branch yet in the repo, although we do have a tag for it. What should we do in the repo?

Do we need to add a RELEASING.txt? We could grab deform's or Pyramid's and modify it.

Would one of the Owners @cguardia @mmerickel @mcdonc @blaflamme either update the "latest" branch to or add me as an Owner? http://readthedocs.org/projects/colander/

@lmctv where did you find that link published? I don't think we publish it anywhere. In the repo's readme, we use the canonical URL docs.pylonsproject.org/projects/colander/en/latest/

[mmerickel]

Yeah, great, I forgot that we created release branches for colander. It looks like I merged a PR yesterday that only went into 1.0-branch as well. Let me fix some stuff up and get back to you.

[lmctv]

@stevepiercy problem is the official "http://docs.pylonsproject.org/projects/colander/en/latest/" link listed at the top of both the github and the pypi page does lead to "colander 1.0b1 documentation"

[stevepiercy]

@lmctv that will be fixed by merging your PR #247.

@mmerickel if we branch to 1.1, we also need to update the docs/conf.py. See #247.

[mmerickel]

Okay, that was terrible but end result is no more 1.0-branch for now. Just master. There's no point in keeping those guys in sync. End result is that RTD has latest pointing to master and there are build versions for the 1.0 and 1.1 tags.

[lmctv]

While it seems readthedocs is still not happy with the 1.0 tag

http://readthedocs.org/projects/colander/builds/3646531/

It's great you managed the big forward merge...

Thank you very much,

lorenzo

On 18/01/2016 00:34, Michael Merickel wrote:

Okay, that was terrible but end result is no more 1.0-branch for now. Just
master. There's no point in keeping those guys in sync. End result is that RTD
has latest pointing to master and there are build versions for the 1.0 and 1.1
tags.

—
Reply to this email directly or view it on GitHub
#246 (comment) Bug
from
https://github.com/notifications/beacon/AA_yOp59bGVTeh_NGG4hbZ0p0aeSc2PTks5pbByAgaJpZM4HGb80.gif

+-------------------------+----------------------------------------------+
| Lorenzo M. Catucci | Centro di Calcolo e Documentazione |
| [email protected] | Università degli Studi di Roma "Tor Vergata" |
| | Via O. Raimondo 18 ** I-00173 ROMA ** ITALY |
| Tel. +39 06 7259 2255 | Fax. +39 06 7259 2125 |
+-------------------------+----------------------------------------------+

[mmerickel]

Damn, that's an issue our system doesn't really deal with atm. Normally I make sure the docs build and then set RTD to just keep serving those docs forever. Re-building old docs isn't something tags work well for.

[lmctv]

I would try to recreate a 1.0-branch, add the missing rtd.txt file and then move the tag to the rtd.txt commit; if we are lucky, all can get back to working order.

[digitalresistor]

Can't move a tag that has been pushed to a remote...

[lmctv]

Maybe a "1.0.0" or "1.0.fix0' new tag could do

[mmerickel]

yeah I was pondering a 1.0-docs tag or branch or something

[stevepiercy]

AFAICT, RTD does not support tags, only branches.

[stevepiercy]

I take that back, there is a way to use tags on a tagged release, but stable can only point to the latest tag and not an earlier tag.
http://docs.readthedocs.org/en/latest/versions.html

IOW, our stable now points to the latest tag of 1.1:
http://docs.pylonsproject.org/projects/colander/en/stable/

So it looks like a branch is the only way to publish a 1.0 version of the docs.

[mmerickel]

@stevepiercy The current 1.0 docs are a tag. RTD supports them fine. We just can't update them as the tag is pinned to a commit.

[stevepiercy]

@mmerickel I don't understand. The current 1.0 docs at http://docs.pylonsproject.org/projects/colander/en/1.0/ returns a 404.

[mmerickel]

because they don't build properly right now steve... see #246 (comment)

[stevepiercy]

@mmerickel what, if anything, should be done?

I have a local recent 1.0-branch where the last merge was PR #242. I could branch from that to 1.0-docs, drop in a rtd.txt, commit and push. Then someone can poke the RTD config.

[lmctv]

leaving to @mmerickel , but it seems the best option to me.