Avoid a dirty git index with readthedocs

[mkelley]

Following discussion at #377 , this PR attempts to fix the version in RTD's "latest" documentation: https://sbpy.readthedocs.io/en/latest

[codecov[bot]]

Codecov Report

Merging #379 (7d79b67) into main (39b0c3c) will not change coverage. The diff coverage is n/a.

@@           Coverage Diff           @@
##             main     #379   +/-   ##
=======================================
  Coverage   76.80%   76.80%           
=======================================
  Files          78       78           
  Lines        6984     6984           
=======================================
  Hits         5364     5364           
  Misses       1620     1620           

[mkelley]

The problem is described at: https://docs.readthedocs.io/en/stable/build-customization.html?highlight=setuptools_scm#avoid-having-a-dirty-git-index

We are using setuptools_scm, which derives the version number from git tags and commits. For every commit beyond the last tag it appends a dev string and a number: https://github.com/pypa/setuptools_scm/

When any git-tracked file is changed, whether or not it is committed, the version is incremented. Apparently readthedocs needs to change docs/conf.py, so this edit tells git to consider that unchanged, which should keep setuptools_scm from incrementing the version, and keeping it clean, like sbpy v0.1.dev172 instead of sbpy v0.1.dev172+g39b0c3c .

Unfortunately, I don't see a way to review the outcome of this edit.

Here is the related astropy PR https://github.com/astropy/astropy/pull/14860

[mkelley]

The build on #378 (i.e., without this edit) was already using the right tag, incrementing beyond v0.4.0 https://sbpy--378.org.readthedocs.build/en/378/ So, I have no idea why "latest" doesn't use it. If this doesn't work, I'll contact RTD to see if they understand it.

[jianyangli]

I see. Now it makes sense to me. Thanks.

I was about to ask you the question of the version number. So let's just go with it now and see how it goes.

[mkelley]

Thanks 🤞🏻

[mkelley]

https://sbpy.readthedocs.io/en/latest/# Closer! But not quite there.

[mkelley]

I've reviewed what setuptools_scm does [1], and I think this is as good as it will get.

[1] https://github.com/pypa/setuptools_scm/tree/main#default-versioning-scheme