documented sphinx usage causes bad metadata on rtd

[brianmay]

Somehow readthedocs gets the wrong version when using setuptools scm.

I asked about this on stack overflow, however got 0 responses.

So asking here in case anybody here has any ideas.
http://stackoverflow.com/questions/35811267/readthedocs-and-setuptools-scm-version-wrong

[jaraco]

I posted an answer there. Best I can tell, setuptools_scm is doing the right thing, reflecting a dirty state of the repository.

[RonnyPfannschmidt]

it might make sense to make readthedocs set an environment variable for us

i would also accept a tested pull request that makes setuptools_scm ignore the dirty state on readthedocs

[peterbrittain]

This is a great package! Shame about this issue, though...

I've just ported my project to use setuptools_scm and fallen foul of it. It took me a while to figure it out and then find this write-up. I would have greatly appreciated a warning on your project readme where you recommend the sphinx setup, especially given that RTD is so prevalent.

Also, if you are thinking of possible workarounds, it occurs to me that conf.py is never really going to be part of the delivered package and that we already have to pass in its name (as per the existing guidance) when building sphinx docs. How about a parameter on get_version that tells it to ignore the relative_to file in SCM too? This could save others from jumping through the same hoops that brianmay and I are already doing.

[RonnyPfannschmidt]

@peterbrittain thanks for your suggestion, unfortunately it does not quite fit, since relative_to tells the root folder and not the relative file

also its hard to correctly do this for other scm's (and even for git it is hard)

i am thinking of updating the docs to get people to always use pkg_resources in sphinx configuration
as well as documenting its use and discouraging use in the conf.py of sphinx

the underlying reason:

1. readthedocs stores the correct data at setup time, so it sits there, its justn ot being used when not using pkg_resources
2. the more i work with scm derived metadata, the more it seems there should be exactly one single point where it gets transferred, and that point seems to always be setup.py call time

[peterbrittain]

Not quite sure that's right about relative_to. The docs say we should pass in __file__ which is the full file name, not just the path. Of course, that doesn't fix the SCM difficulties, so may not be any help...

Given that, it sounds like another source for the docs version (as per your current proposal) might be a better way forwards. Just one further thought: what would this mean for people building sphinx docs outside of RTD?

[RonnyPfannschmidt]

there should be no actual difference, at least thats what i currently believe,

im not sure if i get to this today

[jaraco]

Looks like RTD does provide an environment variable. Setuptools_scm could work around this issue by ignoring the dirty flag when that env var is present.

i am thinking of updating the docs to get people to always use pkg_resources in sphinx configuration as well as documenting its use and discouraging use in the conf.py of sphinx

The downside of this approach is it requires the project to be built and nominally installed (egg-info in . is sufficient) to build the docs, a step which is currently not required. But it does push the version detection into exactly one place, which seems an improvement.

[RonnyPfannschmidt]

@jaraco i am strictly opposed to hacking in a number of special env vars

[RonnyPfannschmidt]

for sphinx the usage via pkg_resources is now documented

[untitaker]

@RonnyPfannschmidt could you reconsider adding a flag to ignore dirty state? Installing my package in rtd's virtualenv is not possible for me due to Rust dependencies, and would in any case slow down build times significantly.

[RonnyPfannschmidt]

@untitaker i'm happy to accept a PR implementing it via env var or passed trough variable, i dont have time/motivation to do it myself in near future