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.)