Dev docs build

[richardjgowers]

I was going to poke one of the Gsoc students to write docs on their feature, but the feature won’t ship for a while. Am I right that the user guide is published instantly? And how much of a hassle would it be to have a dev/master split like we have on the main repo, with dev pushing to a different location? I think @orbeckst had thoughts along these lines too...

@lilyminium probably know something here

[lilyminium]

Yeah, @orbeckst and I talked about this briefly in another issue. When I was doing GSoD I kept (and still have) a little in-development version on my own fork but we should have an official "dev" version of our own.

@orbeckst suggested names like UserGuideDev, DevUserGuide, LatestUserGuide; it might be neater if you just have a subdomain for dev.mdanalysis.org/docs and dev.mdanalysis/userguide.

[lilyminium]

He also brought up RTD versioning which I was going to look into but have not yet -- this would be really useful for people who need a particular version of MDA.

Edit: and having that for docs too would be ideal, actually

[richardjgowers]

Hm, we're using a travis deploy action, but then we can only associate one site with one repo, so not sure if we can have 2 different builds from one repo.

[lilyminium]

I checked out RTD versioning. Not sure how releases work just yet -- although latest is pegged to master, I think if develop is default, latest can point to develop -- but you can build different docs for different branches. I've got one up for an "rtd" branch here at https://mdanalysisuserguide.readthedocs.io/en/rtd/

Also unsure how it works with directories just yet, but you could point to a subdomain and have userguide.mdanalysis.org/en/latest and userguide.mdanalysis.org/en/develop

Edit: if we're going with the RTD I'll merge #68

[richardjgowers]

So looks like using RTD allows us to build multiple branches at the "cost" of having a small advert in the sidebar? Seems like a good idea

[richardjgowers]

Or wait, we can have the dev docs built on RTD with the current setup (gh-pages) for stable docs?

[orbeckst]

On Jun 7, 2020, at 8:15 AM, Richard Gowers ***@***.***> wrote: So looks like using RTD allows us to build multiple branches at the "cost" of having a small advert in the sidebar? Seems like a good idea

IIRC mdtraj docs are not hosted on RTD but amazon and still use versioned docs, see http://mdtraj.org/1.9.3/ <http://mdtraj.org/1.9.3/> including a development branch http://mdtraj.org/development/ <http://mdtraj.org/development/>. We can ask them again. Robert told us a long time ago how he did it.

[lilyminium]

It looks like he just builds docs and puts them in a $version subdirectory that gets copied to AWS, which is probably what RTD does under the hood as well.

I don't really have a problem with advertising RTD if it helps us out, though -- why would you prefer AWS? It's not free, which is a 55c/version/year argument in favour of RTD :-)

[orbeckst]

I don’t want to use AWS; I didn’t know if there was a way to make it work as GitHub hosted. I do like having our docs under MDAnalysis.org, though.

…

Am 07.06.2020 um 18:02 schrieb Lily Wang ***@***.***>:  It looks like he just builds docs and puts them in a $version subdirectory that gets copied to AWS, which is probably what RTD does under the hood as well. I don't really have a problem with advertising RTD if it helps us out, though -- why would you prefer AWS? It's not free, which is a 55c/version/year argument in favour of RTD :-) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[lilyminium]

Both AWS and RTD can point to other domains. I don't know how your site manages subdirectories but if you're open to subdomains, that's just a CNAME record away: http://mdauserguide.minium.com.au/en/rtd/

[lilyminium]

To clarify, that's still being hosted on RTD though, not GitHub. I don't think RTD can set the main domain to a directory like mdanalysis.org/UserGuide/. But it is kind of nice having $thing.mdanalysis.org/$version

And RTD issues free SSL certificates for HTTPS but that takes an hour.

edit: https://mdauserguide.minium.com.au/en/rtd/

[lilyminium]

Sorry for the spam -- just copying docs into the version subfolder on gh-pages should be easily integratable into Travis, though, with keep_history: true. Then the URL just becomes mdanalysis.org/UserGuide/$subfolder . You could either add a new index.html with all the versions or redirect from mdanalysis.org/UserGuide to mdanalysis.org/UserGuide/latest.

[orbeckst]

If we can keep things without ads then I'd be happiest (also, not having to figure out how to fix RTD when it breaks is a bonus). Can we do mdanalysis.org/UserGuide/$version in this way?

For userguide.mdanalysis.org/$version: If we need to do RTD: I think we can easily create new CNAMEs – what else is necessary?

(Our SSL certificates are free from CloudFlare IIRC... need to check.)

[orbeckst]

FYI: https://github.com/MDAnalysis/MDAnalysis.github.io/wiki/DNS – When the DNS was using GoDaddy (registrar) nameservers, we had a whole bunch of A name records that "subdomain-forwarded" to specific sites/directories. The subdomain-forward was GoDaddy service that used A records to their servers. When we moved to Cloudflare (mainly for the free SSL cert), the specific "forwarding" only remained it place for unencrypted http and not https. Cloudflare provides rules ("Pagerules") that can be used for forwarding such as the (still working) https://docs.mdanalysis.org ; however, on the free plan we only have 3 free pagerules and we are currently using 2 (for docs and help) and we used 1 for the workshop. See details on the wiki page.

I am sure that this could all be improved.

It's not a problem to set up new CNAMEs.

[lilyminium]

Thanks for the link @orbeckst! So if I'm reading this correctly, you already have subdomains set up that redirect to the subdirectories? I'm a bit confused because nothing is resolving/redirecting for me other than docs.mdanalysis.org, even over HTTP; and the user guide serves directly to mdanalysis.org/UserGuide (by, I'm guessing, taking advantage of the organisation site repository -> subdirectory naming arrangement?)

I wonder if you could change the URL of the user guide to userguide.mdanalysis.org and have it available both there and mdanalysis.org/UserGuide ? That would be the best of both worlds.

Either way

Can we do mdanalysis.org/UserGuide/$version

yes we can, I have a corresponding PR in the main repo, so it's much of a muchness which URL to access the docs at.

[orbeckst]

So if I'm reading this correctly, you already have subdomains set up that redirect to the subdirectories?

Only https://docs.mdanalysis.org (and https://workshop.mdanalysis.org but that was really meant to be temporary) redirects properly. None of the others do it correctly (only http does it for some, https does not work). I am inclined to scrap all of them and replace them with a CNAME-based scheme instead of something that relies on magic rules at the DNS provider. (Adding 5 additional page-rules would cost $5/month at Cloudflare and although not enormous in cost, any continuous costs are an annoyance.)

[orbeckst]

For a start, I removed all non- or only half-working subdomain redirects.

I also invited @lilyminium and @richardjgowers as admins for the cloudflare DNS account so that you can have a look for yourself.

[lilyminium]

@orbeckst I'm going add a CloudFlare pagerule to redirect docs.mdanalysis.org/additional/paths/here to docs.mdanalysis.org/2.0.0-dev0/additional/paths/here for now. All the links that Google puts on the front page (from the old url) do not redirect and that is quite annoying.

Please let me know if I should undo it!

[orbeckst]

Sure, update the wiiki page and add a note just so that we don’t forget.

…

On Jun 18, 2020, at 4:46 PM, Lily Wang ***@***.***> wrote: @orbeckst <https://github.com/orbeckst> I'm going add a CloudFlare pagerule to redirect docs.mdanalysis.org/additional/paths/here to docs.mdanalysis.org/2.0.0-dev0/additional/paths/here for now. All the links that Google puts on the front page (from the url) do not redirect and that is quite annoying.

[orbeckst]

@lilyminium it would be nice if the User Guide also had a 2.0.0-dev version link in the version selector.

I have no idea where its develop version lives (if it exists at all) because the obvious https://userguide.mdanalysis.org/dev/ redirects to https://userguide.mdanalysis.org/1.0.0/index.html.

[lilyminium]

It did not previously exist but does now. Give this a try?

The develop version of the UG installs the develop version of MDAnalysis, so notation of new features should be made to develop; the master version of the UG installs the latest release (not 1.0.1-dev).

[orbeckst]

Great, thank you!

[orbeckst]

I would consider this issue closed.