Docs versioning and readthedocs.org

[Kodiologist]

When you go to http://hylang.org , you get redirected not to the documentation for the latest stable release, but the one for GitHub master. I think the stable release, not the bleeding-edge version, should be the default.

Also, I think the names "latest" and "stable" are liable to confuse people. I think we should instead use a Git hash or the phrase "GitHub master" instead of "latest", and a version number instead of "stable". "latest" and "stable" are fine for the URLs, but not for the user-facing labels in the sidebar.

I don't know where any of this is configured. It might be a readthedocs.org thing, to which only @paultag, I imagine, has the login information. This said, I'm inclined to think we should host the documentation ourselves instead of on readthedocs.org, if only because it has ads now, which is quite tacky. Assuming it's just a bunch of static pages, I could host it on my VPS.

[gilch]

I could host it on my VPS.

Github can host static pages now. We could use that under hylang ownership, and give Hy Society full access.

[tuturto]

The thing I really like about read the docs is the automation. Documentation for the bleeding edge is up to date (well, as much as we keep it up to date), without us needing to manually update it. We could host it in Github pages (for example), but then we would have to come up with the automation by ourselves. I suppose that's doable though?

[Kodiologist]

I kind of assumed we can reuse whatever automation script already exists, but since I don't know how the automation works, it's hard to say.

[tuturto]

It's under settings | integration & services. One of those nifty features that made GitHub so popular (not the readthedocs per se, but support for various services in general).

[Kodiologist]

There's a switch to turn it on there, but no configuration options that I can see.

[tuturto]

That's the thing. Configuration is at the readthedocs end. On the GitHub side one can just enable/disable the service. And since we don't have access to readthedocs side, we can't change the default branch. Which in turn has lead to several questions about why example code for let doesn't work.

[Kodiologist]

Ah. I guess that comes to show that we either need to move away from readthedocs, or use it in some way other than GitHub's automatic integration, in order to get the kind of control we need over our own documentation site.

[paultag]

I have the login - let me see if I can make it build 'stable' docs off a tag

…

On Mon, Jan 2, 2017 at 12:04 PM, Kodi Arfer ***@***.***> wrote: Ah. I guess that comes to show that we either need to move away from readthedocs, or use it in some way other than GitHub's automatic integration, in order to get the kind of control we need over our own documentation site. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1198 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAIFXxn7Id9lJoEbM2F3LCwOwzZ0rNY7ks5rOS4PgaJpZM4LYo48> .

-- :wq

[paultag]

I think http://docs.hylang.org/en/stable/ should work On Mon, Jan 2, 2017 at 12:05 PM, Paul R. Tagliamonte <paultag@gmail.com> wrote:

…

I have the login - let me see if I can make it build 'stable' docs off a tag On Mon, Jan 2, 2017 at 12:04 PM, Kodi Arfer ***@***.***> wrote: > Ah. I guess that comes to show that we either need to move away from > readthedocs, or use it in some way other than GitHub's automatic > integration, in order to get the kind of control we need over our own > documentation site. > > — > You are receiving this because you were mentioned. > Reply to this email directly, view it on GitHub > <#1198 (comment)>, or mute > the thread > <https://github.com/notifications/unsubscribe-auth/AAIFXxn7Id9lJoEbM2F3LCwOwzZ0rNY7ks5rOS4PgaJpZM4LYo48> > . > -- :wq

-- :wq

[Kodiologist]

It does. This issue is about the names of the two documentation versions, and which is the default.

[paultag]

Why not change the index to contain loud pointers to it, or a banner like Django does?

[Kodiologist]

We can, although I still think the default and the names should be different, like Django's.

[madanh]

The problem stems from the fact that this repo uses a single branch but readthedocs assumes a "master-develop" branching model. Other CI tools might have this assumption by default, so it might be worthy to consider adopting it.

[refi64]

RTD says this can be changed to point to a stable version, so...@paultag want to take a look?

[Kodiologist]

@paultag If you don't want to deal with this, could you give the Read the Docs credentials to me or to one of the other Four Horsemen of Hy Maintenance, namely @kirbyfan64, @gilch, or @tuturto?

[refi64]

Four Horsemen of Hy Maintenance

I like this.

[refi64]

@paultag cough cough

[Kodiologist]

I hope senpai notices us.

[refi64]

[paultag]

@kirbyfan64 @Kodiologist ohai :)

Sorry about that, I think I accidentally muted this thread in gmail -- I tried adding all four of you to rtfd, but only @tuturto had an account, so he got it :)

I'll add the rest of you if y'all post your account names here. I hate being a SPOF :)

[refi64]

I'm kirbyfan64sos.

[Kodiologist]

Thanks, @paultag. I've created a Read the Docs account called "Kodiologist".

[paultag]

Done!

[Kodiologist]

I've changed the default version to "stable", removed advertising, and replaced "latest" with "master" (but, unrelatedly, building documentation is broken at the moment, so there's nothing there at the moment).