doctr deploy

[choldgraf]

OK this should be the right configuration so that doctr deploys the latest documentation on gh-pages. If this all looks good, you should open a PR that inserts your own github API token (or whatever account "controls" shablona). See the docs example at http://predictablynoisy.com/shablona

[arokem]

Sorry. I made a conflict. Could you please rebase?

[arokem]

Also -- it would be good to add a bit of documentation explaining what is going on here (in the README). For example, I am not sure what I am supposed to do to generate a Github API token, and where I am supposed to put it 😄

[arokem]

Also, also: thanks for doing this!

[choldgraf]

did you get rid of the build matrix? That looks like where the conflict is, but it seems that it was totally removed?

[arokem]

It's down here: https://github.com/uwescience/shablona/blob/master/.travis.yml#L17-L20

[choldgraf]

ya but that used to be a big ol' matrix thing with a bunch of explicit environment variables etc...generally doctr would only deploy within one of the builds (the one with python 3) but I'm not sure how to add extra commands to a build if they are only specified w/ a list of 3 strings.

[arokem]

Oh - sorry about that. This seems more civilized though.

How about a bash if statement in the before_install or install block?

[choldgraf]

Cool - sounds good, lemme look into this once I get a little bit of extra bandwidth :-)

[choldgraf]

ok I thought about this a bit and I think I know the best way to do it. However it entails adding a post-success shell script because travis handles multi-line statements strangely. Is that OK w/ you? So basically the PR would add two things:

1. A deploy_docs.sh script in the doc folder
2. A line in travis along the lines of after_success: if $TRAVIS_PYTHON_VERSION == 3.6; then ./doc/deploy_docs.sh; fi

wdyt?

[choldgraf]

mmmk...let's see if the latest push works :-)

[arokem]

Looks like it works! Thanks for doing this. Any chance you could add some documentation to the README, explaining what this is, and how to use it?

[arokem]

One more question: this builds the documentation on every merge, is that correct? How do you handle docs for release version, versus the docs for current master?

[choldgraf]

I'll update the readme for sure!

And yep, it's mostly meant for devdocs versions of documentation. For releases, I think right now something like RTD is still best since it naturally handles multiple versions of things etc. doctr just ensures that the public-facing docs on master are always available. Maybe we can chat about the best way to integrate this w/ shablona since (in my mind anyway) this repo is designed to be a demonstration of best practices. WDYT?

[arokem]

Hey! We should pick this thread back up. I still think we want a doctr deploy into Github pages. I have a new idea: what if doctr deployed the development docs to another repo (something like uwescience/shablona-dev-docs), and then we create a stable docs directory in here (under /docs) and ask github pages to show that directory from master? That would require a manual documentation build every time you release. OTOH, you could probably build some kind of logic around the calls to doctr, so that when it is looking at a tagged commit, it treats it as a release and deploys the docs here?

I am experimenting with all this over on popylar/popylar and popylar/popylar-dev-docs.

[choldgraf]

yo - sounds good! Just got back from England this week and slowly getting caught up. I think what you describe is possible with doctr. If you set up a repo and want me to configure it to push there, let me know and I can give it a shot.

[choldgraf]

Heyyyyy. Did somebody say "stale PR"? :-)

I've been thinking about this a little bit, and I am not so sure that we want to recommend "doctr" as a part of documentation for "beginner-level" developers. I think doctr is super useful, but still falls into the category of "but try getting as far as you can with ReadTheDocs first". Perhaps that means we shouldn't recommend or use it here, and instead mention / link out to it?

What I'd propose is the following:

1. I close this PR because it's a bit out of date.
2. I add a PR that adds documentation to the Shablona repository. The documentation would also describe how it was written etc, with the idea that others could fork/modify for themselves.
3. We'd add a .readthedocs config file, and also have a page documenting how to get readthedocs working for your repository.

what do you think?

[choldgraf]

@arokem since he's probably written this PR off as dead :-D

[arokem]

That all sounds good. To be completely honest, I am thinking of moving away from the shablona way of doing things. The combination of the recent scipy packaging tutorial and the scientific python cookiecutter have made me question whether this really is the best way to do things, even for beginners. But I am not sure whether/what actions to take here.

[choldgraf]

whoah that tutorial looks awesome! For the cookiecutter, have you used it? Do you think it's a good drop-in for Shablona?

I'm going to close this PR now. If you think a docs PR for this repo is still useful let me know

[arokem]

Yeah - it's pretty good, but might not be suitable for beginners. For example, it does show how to use doctr. Here's me teaching a group at NeuroHackademy about packaging using this cookie-cutter (and their awesome documentation).