Use any python to build docs

[dHannasch]

This allows the user to pick which Python they want to use for docs/spell/check, rather than having it hardcoded as Python 3.6.

This also sets envdir to reduce tox environment build time. https://blog.ionelmc.ro/2015/04/14/tox-tricks-and-patterns/

EDIT: Okay, so it turns out that if you specify envdir according to factors, then when none of those factors are present, tox does not leave envdir as the default, instead tox sets envdir to "".

It also turns out that when you set envdir to "" (something that you could only ever do on purpose if, I suppose, you wrote envdir =), tox assumes you meant the directory of the repository itself.

...I have so many questions about both of those design decisions. Hmm, turns out there is a proposal to fix the first, as part of making envdir hierarchically heritable. https://github.com/tox-dev/tox/issues/659 But of course you can already just set a top-level default with

envdir =
    {toxworkdir}/{envname}
    {docs,spell,check}: {toxworkdir}/py{{ cookiecutter.python_version_to_use_for_checks | replace('.', '') }}

https://tox.readthedocs.io/en/latest/config.html#factors-and-factor-conditional-settings

Hrm. What I really want is an option for "instead of specifying a version for docs and check upfront, just use any version that happens to be available." So that a developer could run tox -e check and tox -e docs locally regardless of which Python version(s) they had installed. That's trivial to do for basepython, but I don't see how to do it for envdir.

I can set PYTHONVERSION in setenv and reference it as {env:PYTHONVERSION}, but I can't execute {envpython} --version and set PYTHONVERSION to that.

Hrgh. Nothing's working...Maybe I should take a step back and enumerate what I'm trying to do to see if anything emerges.

• When I run tox, it should only build the docs once no matter how many versions of Python I have available.
• When any developer runs tox, it will build the docs no matter what version of Python they have (as long as it's one of the listed compatible versions).
• The created virtualenv should be reused from the Python version that runs the tests.

I can use an env simply called py, which automatically uses any available Python. And then set the docs to reuse that envdir. That works, but then we still need to have the versions of Python explicitly listed, and so we will run that version of Python twice. That's very annoying.

A complicating factor is that you can't do any chained logic in setenv: https://github.com/tox-dev/tox/issues/341

[dHannasch]

Well ... this template predates the factors feature in tox (test_matrix_configurator was the crappy-in-different-ways solution) grimacing

Eh? Are you replying to "I have so many questions about both of those design decisions."? Both of the design decisions in question are part of the design of tox; it makes no difference whatsoever whether using this template or not.

[dHannasch]

Incidentally, speaking of recent changes to tox, I'm guessing that the reason usedevelop is only on testenv:docs is because usedevelop and skip_install didn't previously play nice together. That's been fixed https://github.com/tox-dev/tox/pull/572, so I think now we could have usedevelop = true at the top-level [testenv] block.

[ionelmc]

You can work around https://github.com/tox-dev/tox/pull/572 by being sane in your configuration - that ain't the problem. The docs env uses usedevelop because:

• code needs to be importable to sphinx.ext.autodoc to work (it imports and enumerates modules if used)
• code needs to be imported from src if sphinx.ext.doctest is used (to prevent source file mismatches as it would try to look for files in src)

We could remove usedevelop with some effort I guess. Still, is that thing relevant? Common envdir still has the env caching issue.

[dHannasch]

Huh? I don't want to remove usedevelop=true. I was just pointing out that it seems like we could use usedevelop=true for everything, if we wanted. It has nothing to do with envdir in any event. (As far as I know.)

[ionelmc]

Ok so will you remove the envdir config or am I missing something here?

[ionelmc]

Oooof. Looks like I forgot about https://github.com/ionelmc/cookiecutter-pylibrary/blob/master/%7B%7Bcookiecutter.repo_name%7D%7D/ci/templates/.travis.yml#L13

[ionelmc]

@dHannasch Well, this got messy. I ran out of time so I reverted it. We should talk about this idea again if you want next week, I'll be traveling for few days.