Add invoke task file

[audreyfeldroy]

At this point, our Makefile contains a fair amount of Python code.

If we used Invoke, it would be cleaner to write tasks containing Python code. Perhaps we could make it a choice:

"task_runner": ["Makefile", "Invoke tasks.py", "None"]

[audreyfeldroy]

If we like the Invoke version, we could even consider getting rid of the Makefile altogether so there is less to maintain.

[eliasdorneles]

Yeah, I've been having similar thoughts.

It's hard to get rid of Makefiles though, because they're used for building Sphinx docs locally (both for the template docs and for the docs template, if that makes any sense :) ). So we'd have to maintain our own versions of those if we were to ditch Makefiles completely, which could be unexpected for anyone used to Sphinx projects built with sphinx-quickstart (as it always generates a Makefile).

Also, the fact that PyInvoke hasn't had a stable release and has a big warning about not promising backward compatibility until 1.0 doesn't make me feel much confident about switching completely either.

Our project is already kinda usable in Windows, provided that you use the command line with Git for Windows (likely true for most people using Git on Windows, but we can point others to it in the docs). This is nice because it also contains other Unix commands (e.g. rm, find) commonly used in a Makefile.

However, even though I believe a Makefile is overall not bad for developer audiences, I think there are still things we can do to mitigate the problems.

So, here is my proposal:

• replace the tasks Makefiles with a self-contained portable Python script called manage.py (like in a Django project)
• keep the Makefile for the docs directories as they are (it's the expected for Sphinx users, and frankly users are already on their own to solve its dependencies when needed -- i.e., you gotta install latex if you want to be able to do make latexpdf)
• add one task for building the HTML docs to this new manage.py script that executes sphinx-build directly, for the Windows users that don't have GNU Make and just want to preview the docs
• update docs to recommend Windows users to install Git for Windows and use it for running the commands
• revisit this once PyInvoke 1.0 is released :)

This seems a decent compromise: it would make cookiecutter-pypackage more Windows-friendly (no need for GNU Make for the common tasks), make the tasks code more maintainable (Python code instead of cryptic Makefiles), avoid the maintenance burden of keeping up with changes in PyInvoke and also avoid maintaining task files for Sphinx docs.

How does this sound?

[eliasdorneles]

And here is a sketch of how I'm imagining that manage.py script: https://gist.github.com/eliasdorneles/5c82cef5d2b16877996a10f12ccc4e7a

This seems good enough for our needs, as we don't have complicated build definitions in our tasks Makefiles, they're essentially just scripts.

[audreyfeldroy]

Thanks for writing this up @eliasdorneles. I'm on the fence here. I think I lean toward using invoke even with that warning since it's so widely used and has been around so long, but I want to think this over a little more.

Another possibility: at PyCon someone showed me that you can add custom tasks to setup.py, e.g. python setup.py bake. I can't find it documented anywhere, but maybe I didn't look in the right places.

[vmuriart]

@audreyr I think you are referring cmdclass that i came across this morning on py.test documentation.

I think this so question/answer gives a bit more information

[eliasdorneles]

So, I was kinda liking the idea of commands in setup.py at first, but I'd prefer not to, mostly because:

1. setup.py is already kinda complicated, I'd like to keep it as simple as possible
2. it will be nice to be able to import stuff from other development dependencies in the script/task file, which it is not cool to do in setup.py

I didn't have the impression that invoke was so widely used before, but seems I'm wrong -- it does even support Windows so I think I'm okay with using invoke too.

So, I hereby update the proposal to use Invoke instead of the manage.py script, still keeping the Makefile for the Sphinx stuff. =)

[eliasdorneles]

Unfortunately I did way too much nitpicking and "yeah, but..." comments above and I'm afraid it drained the energy of people wanting to contribute at the time. I'm sorry for that and I hope to do better next time! :blush:

I would be willing to review and merge a solution for this, with any of the options that @audreyr mentioned (PyInvoke or commands in setup.py). I still lean more towards PyInvoke than setup.py, because adding tasks in setup.py seems to need more code and requires extra discipline about dealing with dependencies.