Try deploying gh-pages only if change to docs dir

[rhc54]

Signed-off-by: Ralph Castain rhc@open-mpi.org

[rhc54]

@ggouaillardet Does this look right to you?

[rhc54]

Fixes #703

[jsquyres]

Is the rationale that if there's an actual diff in the docs directory, then something meaningful changed, and therefore it's worth going through with the deploy?

If so, this might be worth a comment, because Future Jeff / Future Ralph / Future Someone might wonder why this two-step process is here.

[rhc54]

Per @ribab:

Only run gh-pages travisci IF something in mtt/docs changes

[rhc54]

I can add a comment - my question to @ggouaillardet was: does this work the way I think it should?

[jsquyres]

I don't think $testchange will be loaded with 0 or 1.

I think you actually want:

# --quiet inhibits "git diff" output and implies --exit-code
git diff --quiet -- docs
if test $? -eq 1; then

..but then again, I'm slightly confused because this does not appear to be a pure Bourne shell script...?

[rhc54]

I tested the command and it worked exactly as desired - I get a 0 or a 1

[rhc54]

FWIW: the logic of that script is extracted directly from the Travis documentation 😄

[ggouaillardet]

Should the test be if [ $? -eq 0 ] ? $testchange should always be empty.

And because of the set -e we might never run the test if the previous git command failed.

[rhc54]

okay, I changed it - but then we have to also remove the "set -ev" line else we will exit if the command returns a non-zero status code, and Travis is adamant that we not call exit.

[rhc54]

FWIW: my test showed that testchange was always either equal to 0 or 1, not empty

[ggouaillardet]

All I can think of is this is not bash shell (the name and syntax suggests this should be a bash shell).

I will double check the Travis syntax tomorrow.

Btw, what is the rationale for this PR ? Is this a simple optimization (e.g. it does not fix anything) to save Travis resources ?

[jsquyres]

@ggouaillardet I asked a question on the MTT devel list to see if we could not re-deploy every time there's a commit to MTT. It causes a git push + email in the docs tree, and the only thing it contains is a timestamp update in the latex source. E.g.: 41bbb3c

[rhc54]

Yeah, I'm not convinced this is actually worth all this angst, but was willing to spend five minutes on it just to keep the git repo from unnecessarily growing. If it goes back/forth much more, though, I'll drop it as not worth the time.

[jsquyres]

BTW, is the latex dir part of the docs dir? I ask because the meaningless timestamp update occurs in the latex dir.

[rhc54]

Danged if I know. @ggouaillardet Here is the link to the Travis doc:

https://docs.travis-ci.com/user/customizing-the-build/#implementing-complex-build-steps

[jsquyres]

Hah! Yeah, I agree it's not worth a huge amount of time.

But... @ggouaillardet if you could spend 5 minutes on it tomorrow, that would then be a global total of 10 minutes of each of our time, and if that carries this over the finish line, #winning. 😉

[ggouaillardet]

@rhc54 the doc simply states a script can be executed. I did not read the script is supposed to output a Travis config that will be parsed dynamically.

Also, from the deploy doc section

An optional phase in the build lifecycle is deployment. This step can’t be overridden, but is defined by using one of our continuous deployment providers to deploy code to Heroku, Engine Yard, or a different supported platform. The deploy steps are skipped if the build is broken.

So at first glance, I do not think this looks right (we would have to modify the Travis provider in order to achieve the desired result). The right approach could be to manually push to the gh-pages branch as discussed at
https://stackoverflow.com/questions/23277391/how-to-publish-to-github-pages-from-travis-ci

Makes sense ?

[rhc54]

I'm open to whatever solution (including doing nothing) someone wants to pursue 😄

[ggouaillardet]

@rhc54 Any reason why you closed this PR ?

Right now, doing nothing is the best option. The rationale is the latex file contains some time stamps, so there is always something to push. (It looks like a latex bug/lack of feature, that is likely fixed in the latest version).

I do not think the desired behavior can be achieved with some configuration only.
I would advocate to write a custom script, such as the one in Stack Overflow.
If git push —force ... is not acceptable on the gh-pages repo, then some extra steps are required.
I found an example on SO, and I can make a proof-of-concept if needed.

[rhc54]

I closed it because you indicated it was wrong, so no point in retaining it. If you believe you have a way of solving it, feel free to pursue it. Just don't burn a ton of time on it as it isn't something that critical.

[jsquyres]

@ggouaillardet If you're interested...

I think this PR had the right idea:

• Doxygen generates several different flavors of the same docs.
• Therefore, if there's changes in one of them, there's changes in all of them.
• But there's a bug/feature that the latex flavor always changes (it updates timestamps).
• So it might be sufficient to check to see if there's any changes in the HTML docs (which are assumedly in a different directory than the latex docs). If git diff --quiet returns a nonzero exit status in the HTML docs, then there's actually changes in the docs. If it returns zero, there's no meaningful changes.
• If there are meaningful changes, then we should run the deploy. If not, then don't bother deploying.

[ggouaillardet]

@rhc54 @jsquyres I think I now got the rationale right. The missing piece of the puzzle - from my point of view - is we need to (sort of) git diff docs/html instead of git diff docs, at least as long as the latex file contains some timestamps. I just made #711.

I assume the github oauth token is from Ralph's account, so I hardcoded GH_USER=rhc54. Regardless this has to be updated or not, we might want to encrypt this alltogether with GH_TOKEN.
Because of travis security rules, Ralph might also have to be the author of this PR before merging it.

[rhc54]

I think, but could be wrong, that you won't need the GH_USER once this is committed into the actual repo as Travis is executed as me (since it is my token). Dunno about authorship - we can just try it as-is and see if it barks.

I have no idea how to test it other than commit and see what happens. Note that we already lost some of the pages as reported in #705. No idea why.

[ggouaillardet]

yep, it seems the user is sort of encoded in the oauth token. I will update the PR accordingly.

[rhc54]

Kewl - I'd say let's give it a try. If all works okay, we can then add the ---force option as I can't see any reason for keeping the gh-pages branch history. We can always regenerate the docs for a particular hash if someone wants to do so.