docs: setup ghpages CNAME

[mauro3]

The new manual-system got merged: JuliaLang/julia#18588 . Shouldn't julialang.org link to that now? The links are in this post.

[MichaelHatherly]

The docs need to stay at the current address (docs.julialang.org) otherwise every link to them from anywhere online will break, so nothing should be change here.

We just need to set up the ghpages CNAME as mentioned in JuliaLang/julia#18588 (comment), but that can only be done by someone with access to wherever the domain was registered.

[ViralBShah]

What exactly needs to be done? I looked around a bit and tried a few things, but it was not clear to me. Note that in the github julialang organization settings, it says:

[MichaelHatherly]

I think what we need is similar to how the pkg.julialang.org subdomain is hosted on https://github.com/JuliaCI/pkg.julialang.org. We just need to replicate that for docs.julialang.org and https://github.com/JuliaLang/julia.

[ViralBShah]

pkg.julialang.org is easy because it is a different github org. I don't know how to have one project page in the github org (website) serve from master, and another one in a github project (docs) serve from gh-pages.

cc @Keno who can help set this up as well and may know this better in any case.

[ViralBShah]

Currently, trying to see the documention from julialang.github.io/julia/latest doesn't work because it tries to redirect to julialang.org (which is served from a different repo due) and fails with a 404.

[StefanKarpinski]

It's non-trivial to even find which page describes what to do:

https://help.github.com/articles/setting-up-a-www-subdomain/

tl;dr: add CNAME record for the docs.julialang.org subdomain pointing at julialang.github.io.

[ViralBShah]

That does not work as I described above. It sends the request to the julialang.github.com repo, not this one. For example, I set up a newdocs.julialang.org CNAME, but gives a 404.

[MichaelHatherly]

pkg.julialang.org is easy because it is a different github org.

The JunoLab site is setup like this as far as I can tell and seems to be all hosted from a single org. @MikeInnes was there anything special that needed to be done to make that work?

julialang.github.io/julia/latest

Also needs an en/ in the URL: http://julialang.github.io/julia/en/latest.

[ViralBShah]

Thanks. This works: http://julialang.org/julia/en/latest/

[mauro3]

But this doesn't http://docs.julialang.org/ (in case you're not aware).

[ViralBShah]

I am just mucking around with it as we speak.

[ViralBShah]

Reverted it.

[ViralBShah]

AFAICT, newdocs.julialang.org has the correct setup, but doesn't work. The CNAME points to julialang.github.io.

[MikeInnes]

Here are the settings I have for docs.junolab:

As well as this file at the root of the repo. I don't think I did anything special above the instructions that github gives; bear in mind can take 24 hours for DNS changes to propagate.

[ViralBShah]

Fixed by c496ab65ea0dd112fe89a317fd5778867f106e98

[ViralBShah]

This works now: http://docs.julialang.org/en/latest/

but docs.julialang.org doesn't yet.

[ViralBShah]

@MikeInnes says we could set up redirects:
https://help.github.com/articles/redirects-on-github-pages/

[MikeInnes]

The option is to have an index page with an HTML redirect (e.g.), which may work better on second thoughts.

[MichaelHatherly]

That's what I've been doing with Documenter, https://github.com/JuliaDocs/Documenter.jl/blob/gh-pages/index.html, seems to work well. Thanks @ViralBShah, @MikeInnes for sorting this out!

[ViralBShah]

Can I just add index.html to the gh-pages branch on the toplevel with similar text?

[MichaelHatherly]

Yes, that should work. Probably best to redirect to the stable docs.

[ViralBShah]

Did that but doesn't seem to work. Is the .nojekyll file the issue?

[MichaelHatherly]

Hmm, could be. We probably don't really need .nojekyll anyway.

[MikeInnes]

It may take a sec for github to re-cache stuff

[MikeInnes]

aaaand it works :)

[ViralBShah]

Just deleted .nojekyll.

[ViralBShah]

How does one find other versions of the manual? Should the readthedocs be available on a different URL?

And how do we link to the latest docs?

[MichaelHatherly]

latest has a version picker on the left side, but the locally built sphinx docs don't have any way of knowing about other versions; that's something that readthedocs adds in itself I believe.

We could try manually adding a version selector to the built docs for 0.3-0.5.

[ViralBShah]

Or perhaps the index.html can just let you pick any version of the manual?

[MichaelHatherly]

Or perhaps the index.html can just let you pick any version of the manual?

That could as well. Simpler too.

[ViralBShah]

And Thank you for all this amazing work! I just did the dns switch. :-)

[MikeInnes]

Looks like the css is no longer loading on the docs site. Could this be due to the .nojekyll change?

[ViralBShah]

The css seems to work for /en/latest, just not for /en/stable. Thoughts?

[ViralBShah]

Actually the version picker is ok (maybe no need to have index.html), but it doesn't seem to be present on other versions except for the latest.

[MikeInnes]

The resources for stable appear to be stored in a folder called _static, which could be special cased by jekyll in some way. @MichaelHatherly will likely know more about that.

[MichaelHatherly]

Yeah, I think I know what's going. One moment...

[MichaelHatherly]

Well, you're meant to be able to force the inclusion of certain folders with an include: (https://jekyllrb.com/docs/configuration/), but it doesn't appear to be working. I'm not too familiar with jekyll so perhaps I'm just doing something wrong.

[MichaelHatherly]

JuliaLang/julia@770c793 = 🎉?

[mauro3]

Now stable points to the old-style docs for me (latest is still the new).

[MichaelHatherly]

Now stable points to the old-style docs for me (latest is still the new).

The old-style docs are the "new" old docs, i.e. non-readthedocs ones, so it does seem to be working as it should now.

[mauro3]

Ah, yes, that makes sense: the new doc-system was not back-ported to 0.5, thus they are still as they always were. However, then the problem remains that from the older docs there is no way to switch to other versions. Only the 0.6-docs have a drop-down menu.

[ViralBShah]

I think we should backport the drop-down menu to the old versions - assuming that is not difficult to do.

[MichaelHatherly]

Yes, I'll see whether I can patch the version selector into the old docs.