Add option to transfer post-processing scripts about doctr HOT 3 OPEN

The --exclude thing is probably a bug.

--transfer as you describe it is already what the deploy directory is. I think we just need to add support for multiple deploy directories/files, and fix --exclude so that it works (and also document this whole thing in the recipes docs).

from doctr.

Do you mean multiple --built-docs (#221)? So if I had the documentation in docs/build/html and my post-processing scripts in .travis, I'd invoke doctr deploy as something like

doctr deploy --built-docs docs/build/html --built-docs .travis --exclude .travis $DEPLOY_DIR

Actually, that seems weird, since currently (if I undestand correctly) --built-docs and $DEPLOY_DIR form a pair, in that the folder specified by --build-docs will be copied to the $DEPLOY_DIR on the gh-pages branch. You'd need multiple pairings. It also wasn't quite clear to me from the documentation of --exclude whether currently its argument is relative to $DEPLOY_DIR or to the root of the gh-pages. It would seem that if there are multiple --built-docs/$DEPLOY_DIR, the --exclude would have to be relative to the root.

To be honest, I don't have a clear mental picture of how doctr deploy operates. It seems like something along the lines of

• create an empty temporary directory (let's call it root) and initialize it as a new temporary branch
• copy the --build-docs directory to root/$DEPLOY_DIR and git add it
• run --command with root as the current-working-directly, which can make changes within root and git add them
• create a commit on the temporary branch
• cherry-pick that commit onto the gh-pages branch and push

That wouldn't delete files that are missing in the --build-docs directory from gh-pages, though (which I think doctr does, so the above model likely isn't accurate).

Here's the simpler model that I initially thought was what doctr was doing (but definitely not what's happening):

• check out gh-pages to a temporary folder
• git rm -rf $DEPLOY_DIR in the gh-pages checkout if it exists
• copy the --built-docs directory to the $DEPLOY_DIR in gh-pages
• run the --command, which can modify any files (it wouldn't have to git add them if this model was correct)
• Commit on gh-pages (with git commit -a) and push

I have no idea what the --no-sync and --no-temp-dir options do. Anyway, sorry for ranting, and if I'm a bit thick on what you're proposing. It might be a good idea to give an overview of the correct mental model in the documentation, though.

For now, I've managed to get by post-processing to work by using

--command="git show $TRAVIS_COMMIT:.travis/docs_post_process.py > post_process.py && git show $TRAVIS_COMMIT:.travis/versions.py > versions.py && python post_process.py"

from doctr.

Reading the source code was illuminating regarding the deployment procedure. The missing piece was the .doctr-files log using during synchronization, and the fact that the --command runs after synchronization, but before git add/git rm. I created PR #356 to make this part of the documentation

from doctr.