阅读文档和 setuptools scm 版本错误答案

【问题标题】：readthedocs and setuptools scm version wrong阅读文档和 setuptools scm 版本错误
【发布时间】：2016-03-05 07:13:38
【问题描述】：

我刚刚更新了一个包以使用 setuptools_scm，发现 readthedocs 中的版本号有误。

http://sshuttle.readthedocs.org/en/v0.77/ 显示：

Version: 0.78.dev0+ng083293e.d20160304

但是由于版本 083293e 有 0.77 标签，版本字符串应该只是 0.77

看起来 readthedocs 可能会在构建之前对我的源代码进行更改。

我查看了 readthedocs 构建日志，它似乎在某个阶段 (0.77) 具有正确的版本，但这是在它构建文档之前。

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

构建文档时构建日志没有提及版本。

有办法解决吗？

谢谢

【问题讨论】：

为了后代，这个问题也是raised with setuptools_scm。
刚刚向readthedocs提出了这个问题。

标签： setuptools read-the-docs setuptools-scm

【解决方案1】：

我看到你正在构建this project。

显然，在确定版本之前，有些东西正在改变存储库状态。您可以通过在自己构建文档之前更改其中一个文件来复制类似的行为：

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

在阅读文档文档中，有一个description of the process。

在那里，您可以看到 RTD 执行的步骤，即 (a) 运行 setup.py install 然后 (b) 在 requirements.txt 中安装需求。

我已经确认这些步骤都不应该改变回购状态。

然而，它没有解释“版本”的来源，或者 update_imported_docs 的作用。我怀疑问题在于阅读文档所做的修改回购的微妙之处。

这里是one place where the conf.py file gets modified。

也许将docs/conf.py 添加到您的 .gitignore 将允许忽略这些更改，因此在计算项目版本时不会影响您的工作状态。

【讨论】：

我尝试将docs/conf.py 添加到.gitignore，然后更改docs/conf.py；但是 scm 仍然检测到更改。我预料到了这一点。不知道我理解为什么 RTD 需要改变任何东西。或者如果确实如此，它可能应该复制而不是更改原件。不会屏住呼吸等待......
接受这个答案，因为它可能确实解释了为什么我会看到这种行为，即使它没有给出解决方案。
接下来，我会尝试在 conf.py 中添加一个 subprocess 调用到 git diff 或类似的，然后在 rtd 构建期间检查日志以查看 repo 中具体发生了什么变化。
完成。打印语句并没有完全按计划进行，但是无论如何您都可以看到相关信息。 readthedocs.org/projects/sshuttle/builds/3880804
所以我们已经确认 RTD 正在改变存储库中的 conf.py。因此，setuptools_scm 正确评估了项目与标记时的状态不同（因此将标记版本用于不同的代码是不正确的）。要解决此问题，您可以修补 setuptools_scm 以忽略 RTD 上的此文件，或者有一种方法可以将 conf.py 存储为模板，然后有一个预构建步骤将内容复制到 docs/conf.py （未在 repo 中跟踪）。

【解决方案2】：

https://github.com/pypa/setuptools_scm/issues/84 已更新以记录此内容

我们将与 sphinx 团队合作，提供此过程的自动化/无痛版本

【讨论】：

【解决方案3】：

setuptools_scm 的文档现在有 instructions 关于如何与 readthedocs 一起使用：

不鼓励使用 sphinx 本身的 setuptools_scm，而是在可编辑/真实安装后使用 pkg_resources：
from pkg_resources import get_distribution
release = get_distribution('myproject').version
# for example take major/minor
version = '.'.join(release.split('.')[:2])
根本原因是，像 readthedocs 这样的服务有时会更改工作目录充分的理由和使用已安装的元数据可以防止使用不必要的不稳定的数据。

这避免了根据其他答案使用 kluges 的需要。

【讨论】：