how to handle multiple releases of a repo?

[choldgraf]

Just wondering if / how folks have thought about handling multiple releases of a package. It seems like doctr is mostly just for showing the latest docs, which is mostly probably fine, but as larger packages want to adopt it'll need to handle docs for legacy versions, yeah?

[asmeurer]

I haven't thought about it at all. Doctr has so far just been designed for dev documentation. I think at least https://github.com/drdoctr/doctr/issues/29 is a prerequisite here.

[choldgraf]

So then is the general suggestion to use RTD for versioned-documentation, and use doctr for devdocs versions?

[asmeurer]

Well the whole idea here was to not require RTD. Some docs can’t be built in RTD, and in other instances you don’t want the extra complexity.

[choldgraf]

Sure - I'm just thinking of what to suggest to people in the meantime. E.g., would you tell a developer of a major project that needs multiple docs versions not to use doctr?

[asmeurer]

How exactly are you wanting the workflow to work? Is it just a single build, presumably done on a tag? In that case, we need #29. Is it continuous builds from a branch? That can already be done https://drdoctr.github.io/doctr/recipes.html#deploy-docs-from-any-branch. Doctr won't handle the version popup like RTD has because it's agnostic to the actual pages it is deploying.

By the way, will you be at SciPy? If so, we should get together and discuss this there.

[choldgraf]

yep! I will be there :-)

In this case I am partially speaking from packages I'm working with, but also just trying to bring up ideas for future consideration!

[asmeurer]

Cool. I'll be there all week (tutorials, conference, and sprints). Let's discuss it there. If we come up with any concrete ideas we can sprint on them (doctr was born out of the SciPy sprints last year, so it would be fitting to work on it there again).

[choldgraf]

Sweet - I'll be there for at least some of the hack sessions at the end. Looking forward to chatting about this!

[CJ-Wright]

Has there been any progress with this? Is it related to https://github.com/sympy/sympy_doc/pull/19? Could this be handled via reaver?

[asmeurer]

I have https://github.com/drdoctr/doctr/pull/225. It needs a final run through to check that everything works. I haven't had a chance to do any work on doctr since SciPy.

[jcrist]

It looks like there's been some work done on this since the last comment, but I can't quite figure out how to make this work myself (if it's even possible). What's the status of this? Any tips/tricks for getting multiple releases built using doctr?

[gforsyth]

@jcrist -- I haven't tried out @asmeurer 's changes in #225, but I think if you add this to your .travis.yml

  - if [[ -z "$TRAVIS_TAG" ]]; then
      DEPLOY_DIR=dev;
    else
      DEPLOY_DIR="version-$TRAVIS_TAG";
    fi
  - doctr deploy --build-tags --built-docs build/ $DEPLOY_DIR

and have Travis set to run on pushed tags, then re-push any existing version tags then Travis should trigger on each of those tag pushes and push the corresponding docs (assuming you install doctr from master because I don't think #225 is in a release).

If that doesn't work, there's the more manual way that xonsh uses to maintain dev + latest release docs, which could be repeated for more versions (although it's highly inefficient): https://github.com/xonsh/xonsh/blob/master/.travis.yml#L64-L75

[asmeurer]

You can also try out this https://github.com/goerz/doctr_versions_menu

[asmeurer]

And this is how SymPy does it. Our release docs are currently uploaded by our release script, not doctr, but the dev docs are released by doctr. https://github.com/sympy/sympy_doc/blob/gh-pages/generate_indexes.py.