Clarify documentation for v2 and v3 CLI/API differences

[baileythegreen]

@widdowquinn

This is one of the first things I think needs to be done; I've seen at least five separate instances (like #238 just now) of the exact same conversation where people try to use pyani v0.3+ commands with pyani v0.2.10. I ran into some confusion there myself when I was going over it. Seems like it would save time all around.

I'll assign it to myself (to work on in a few weeks), unless you want to do it?

[widdowquinn]

I'm happy for you to take it on if you like. It's been nagging at me for a while, so it would be great to get it clear enough that no new issues arise.

I wonder if a fake pyani script that informs users about their current version and the specific CLI they should be using might be a useful addition to v2.

(my plan was that v0.3 is at least kind of backwards-compatible via wrappers with the same names as the v2 scripts…)

[baileythegreen]

What do you mean by a fake script? Like just an example script that comes with the installation? Heavily commented?

[widdowquinn]

Essentially a script that, when called, does nothing but give a message to the user that they have v2 installed, but are trying to use a CLI command that only works in v3, and points them gently to some online documentation.

[baileythegreen]

So, one that runs if they try to call pyani; except that's only going to work if the fake script is on their path, somehow. Might be an issue if they install version 2, then go away and come back to try to run it via the wrong CLI in a different location.

[widdowquinn]

The way I think we could make it work is via setuptools.setup() in the setup.py file.

We could define an entry_point which points to a function that returns an appropriate string to sys.stdout, e.g.

setuptools.setup(
    [...]
    entry_points={
        "console_scripts": [
            "pyani = pyani.pyani_tools:pyani_error_msg",
        ]
    },
    [...]
)

and, in pyani_tools.py:

def pyani_error_msg():
    msg = "This is the message for the user"
    sys.stdout.write(msg)

[widdowquinn]

The approach above would point pyani at the command-line to the error message, if v2 is installed. If v3 was later installed (and in the $PATH) it should override this. Or am I overlooking something?