Update mkdocs.org automatically on a release

[d0ugal]

Travis now releases to PyPI for us, it would be great if it could then also run mkdocs gh-deploy for us too.

Somebody recently figured out how to do this, we can maybe lear from it: https://mwop.net/blog/2016-01-29-automating-gh-pages.html (it looks somewhat complicated, it would be great if we could make this easier for people).

[waylan]

Your first link appears to be bad.

In any event, I don't get this. Why does Travis need to deploy? Why can't you run a couple commands locally to deploy? I realize it is sometimes a problem when you forget which options you need each time. But a simple script which provides those options as defaults works fine. That's why I created a makefile for Python-Markdown. The two commands make deploy and make docs takes care of everything (granted, my script does not currently upload docs - but that is for an unrelated reason). And if I forget the subcommands, make help reminds me. Just by adding this, deploying a new release is no longer a chore and I'm more inclined to do it more often. And it is a lot easier to develop that the hoops you have to jump through to get Travis to deploy.

[waylan]

I should note that if some additions were made to MkDocs which made it easier to deploy from a CI Server, that would be beneficial. In that case, it might make sense for MkDocs to eat its own dog food. But I doubt we would want to include a Travis specific script. Perhaps a deploy script which only deploys if an environment variable is set (perhaps MKDOCS_DEPLOY). After all, different users will have different criteria to determine when a deploy should happen and may be using different CI services. Users could then set up whatever then wanted as criteria and set the environment variable to True or False. Then, when the deploy command is called, it will act on that variable. Perhaps adding a flag to the current deploy command would be sufficient:

mkdocs gh-deploy --if MKDOCS_DEPLOY

[d0ugal]

In any event, I don't get this. Why does Travis need to deploy?

Simply, I want to automate as much as possible to remove dependency on me. It isn't much, but the release process is knowldge in my head and nowhere else, if that is all handled by travis and I (or possibly somebody at some point) just needs to push a git tag, then great!

Also, I would also like to see if we could have the docs for master be built and available at mkdocs.org/master/ or similar. So that would be updated on each commit, then a tag would update the main docs.

[d0ugal]

But yeah, part of this issue is intended to make it easier to integrate MkDocs into a CI server. So I doubt I would follow the linked approach directly, but that gives me a good example of the problem, I just have the advantage that I can tweak MkDocs to make it easier ;)

In a way this could be considered a duplicate of #632. So maybe I should just use that.

[laf]

Is this something that still needs doing?

We've recently adopted mkdocs for the docs in our librenms/librenms and wanted to do the same thing. When a pull request to master branch is merged, we trigger travis to push a new build of our docs site to docs.librenms.org.

I'd be happy to help with the same here if you still need it?

[waylan]

Looking at our travis.yml file, it appears that we deploy a release to PyPI. However, we still have nothing deploying the documentation. A pull request would certainly be welcome.

Note, in our case the master branch is the "dev" branch, so we would only deploy docs on tags (releases). If we had docs for each version, then it might make sense to update the "dev" version of the docs on each commit to master. But until then (see #193), we only want to deploy on tags.

[d0ugal]

It is a nice to have, but not particularly urgent.

[laf]

@d0ugal it's probably the only thing I can contribute back at the moment :)

@waylan Thanks, I'll take a look this weekend time permitting and draft something up.

[laf]

Sorry guys I didn't get round to this at the time.

Can I just check how it works now. Do you publish the site to GitHub Pages or somewhere else? I'm assuming it's GH Pages as you have a gh-page branch, so if we did a hook via Travis to push to that it would be ok?

[d0ugal]

Yes, it is on GitHub pages. Doing it with Travis would be best. I have done something similar here:

https://github.com/d0ugal/retrace/blob/master/.travis.yml#L31-L37

However, we only want MkDocs to do this on a release - that other project does it on every commit as it is much smaller and released often.

[laf]

We do it on merges at the moment but it should be possible to do on release. I'll check into it.

[d0ugal]

Yeah, you just need to use after_deploy rather than after_success.

https://docs.travis-ci.com/user/deployment/pypi/#Running-commands-before-and-after-release

[pawamoy]

I will close this in favor of #3642, and tag it with the "Priority" label. We're not using Travis CI anymore so the comments here are only historically helpful 🙂