3

I have a package I just updated to use setuptools_scm and found the version number is wrong in readthedocs.

http://sshuttle.readthedocs.org/en/v0.77/ shows:

Version: 0.78.dev0+ng083293e.d20160304

however as version 083293e has the 0.77 tag, the version string should be just 0.77

It looks like readthedocs might be making changes to my source code before building.

I have looked at the readthedocs build logs, and it seems to have the correct version at one stage (0.77), however this is before it builds the documentation.

Processing dependencies for sshuttle==0.77
Finished processing dependencies for sshuttle==0.77

The build logs don't mention the version while building the documentation.

Is it possible to solve this?

Thanks

gerrit
  • 24,025
  • 17
  • 97
  • 170
Penguin Brian
  • 1,991
  • 14
  • 25

3 Answers3

1

I see that you're building this project.

Clearly, something is mutating the repository state before the version is determined. You can replicate similar behavior by mutating one of the files prior to building the docs yourself:

(sshuttle) $ python setup.py --version
0.77
(sshuttle) $ cat >> setup.py
# a comment
(sshuttle) $ python setup.py --version
0.78.dev0+ng083293e.d20160403

In the read the docs docs, there's a description of the process.

There, you can see the steps RTD does, namely, (a) run setup.py install then (b) install requirements in requirements.txt.

I've confirmed that neither of those steps should be mutating the repo state.

What it doesn't explain, however, is where that 'version' comes from, or what update_imported_docs does. I suspect the issue lies in something subtle that read the docs is doing that modifies the repo.

Here's one place where the conf.py file gets modified.

Perhaps adding docs/conf.py to your .gitignore will allow those changes to be ignored and thus not dirty your working state when calculating the project version.

Jason R. Coombs
  • 41,115
  • 10
  • 83
  • 93
  • I tried add ``docs/conf.py`` to .gitignore, and then changing docs/conf.py; however scm still detects the change. I expected this. Not sure I understand why RTD needs to change anything. Or if it really does, it probably should make a copy instead of changing the original. Won't hold my breath waiting... – Penguin Brian Apr 04 '16 at 07:44
  • Going to accept this answer, as it probably does explain why I am seeing this behaviour, even though it doesn't give a solution. – Penguin Brian Apr 04 '16 at 08:12
  • Next thing, I would try adding a `subprocess` call to `git diff` or similar in conf.py and then check the logs during the rtd build to see what specifically is changing in the repo. – Jason R. Coombs Apr 04 '16 at 11:38
  • Done. The print statements didn't exactly go to plan, however you can see the relevant information anyway. https://readthedocs.org/projects/sshuttle/builds/3880804/ – Penguin Brian Apr 06 '16 at 01:31
  • So we've confirmed that RTD is mutating the conf.py, which is in the repository. Hence, setuptools_scm is correctly assessing that the project is not in the same state as when it was tagged (so it would incorrect to use the tagged version for code which differs). To work around this, you could patch setuptools_scm to ignore this file on RTD, or maybe there's a way you could store the conf.py as a template, and then have a pre-build step to copy the content to docs/conf.py (untracked in the repo). – Jason R. Coombs Apr 12 '16 at 09:08
  • I have a work around. Don't like it, however it does work. https://github.com/sshuttle/sshuttle/commit/89c5b570190a32da2cfaea061b87005177fea16d – Penguin Brian Apr 18 '16 at 01:54
0

https://github.com/pypa/setuptools_scm/issues/84 has been updated to record this

we will be working with the sphinx team to provide a automated/painless version of this process

0

The documentation for setuptools_scm now has instructions on how to use with readthedocs:

It is discouraged to use setuptools_scm from sphinx itself, instead use pkg_resources after editable/real installation:

from pkg_resources import get_distribution
release = get_distribution('myproject').version
# for example take major/minor
version = '.'.join(release.split('.')[:2])

The underlying reason is, that services like readthedocs sometimes change the workingdirectory for good reasons and using the installed metadata prevents using needless volatile data there.

This avoids the need to use kluges as per the other answer.

Penguin Brian
  • 1,991
  • 14
  • 25