Allow amend commits for development doc builds

[leouieda]

Currently, doctr makes a new commit to gh-pages every time something shows up in the master branch. This might be problematic for projects with a lot of activity and image heavy docs, like matplotlib or other sphinx-gallery users. The size of gh-pages might ballon due to the large amount of binary files.

My current setup (using tokens), amends the last commit if the current build is not a release:

if [[ "${VERSION}" == "dev" && `git log -1 --format='%s'` == *"dev"* ]]; then
    echo -e "Amending last commit"
    git commit --amend --reset-author --no-edit
else
    # Make a new commit
    echo -e "Making a new commit"
    git commit -m "Deploy $VERSION from TravisCI"
fi

This keeps the amount of commits down and the branch size under control.

I tried reproducing this setup with doctr using a custom command that makes the amend commit before doctr does: https://github.com/leouieda/test-doctr/blob/master/deploy-gh-pages.sh This doesn't work because doctr sees that there is nothing to commit and doesn't push. Plus, it's an ugly hack.

What would make all of this work for me would be to introduce a flag to tell doctr to --amend the commit and a way of inserting a custom comment in the commit message (#282) (so I can detect if the commit should be amended).

I'd be happy to implement this myself if someone can point me to the right place in the code base.

[asmeurer]

Agree. It shouldn't be the default, but there should be a flag for it for people who want it. See also https://github.com/drdoctr/doctr/issues/213. Combining it with a custom comment sounds good. Although it should by default probably only amend if the commit in question was made by doctr.

It shouldn't be hard to implement. The command to commit is here. So a command line flag should be added in __main__.py, and passed through. There should also be a flag force added to push docs and if amend is True it should set it to True. There's already a last_commit_by_doctr function that checks if the last commit was doctr. The custom message should be similarly easy to implement.

For testing, we should set up a separate testing repo whose gh-pages has force pushed commits, to avoid conflicting with the existing tests on the drdoctr/doctr gh-pages (I think I have branch protection enabled on this repo's gh-pages to prevent anything bad from happening from a bug). I can set this up.

[leouieda]

Sounds good. I'll take a crack at this. There is already a --forge flag for something else, though. It might not be needed explicitly since it only makes sense to force if we amend or rebase. I could assume that if amend is True, I'll need to force push. What do you think?

[asmeurer]

Yes that is what I was thinking. Add --force to the git push automatically based on whether it is needed.

[bashtage]

This would be helpful to me as well. Perhaps --amend?

[asmeurer]

--amend seems like a good flag name.