Change the documentation URL on GitHub to point to the stable version

[ocefpaf]

Hi folks, please ignore if pointing to the latest is by design but it is probably easier for end user if the default doc URL, shown in the image below, points to the stable version at https://searvey.readthedocs.io/en/stable/

[pmav99]

Fixed

Thanks @ocefpaf

[ocefpaf]

Thanks! That was fast.

BTW, I'm not an expert on poetry and poetry's way of handling version but I noticed two things:

1. There is no searvey.__version__ for users to inspect and,
2. it seems that the recorded stable version has some captured a "dirty" git environment.

I can fix that if you choose to move to setuptools_scm but I bet a poetry expert can easily fix this here without the need to move to another way of handling versions.

[pmav99]

As far as __version__ goes, AFAIK nowadays it is suggested to use importlib.metadata instead. That being said, I guess that we could add something like this in __init__.py

__version__ = importlib.metadata.version(__name__)

This wouldn't help someone who just browses the code, but you could use __version__ after importing searvey.

Regardless of that, we are using a poetry plugin for handling the versions: https://pypi.org/project/poetry-dynamic-versioning/

I am quite familiar with poetry, but It's the first time I use this plugin so I wouldn't call myself an expert on it. Anyhow, the idea is that the version gets generated dynamically depending on the number of commits that have passed since the latest tag. For example:

$ pip install --force-reinstall searvey  > /dev/null                           
$ python -c 'from importlib.metadata import version; print(version("searvey"))'
0.3.5
$ pip install 'git+https://github.com/oceanmodeling/searvey.git' > /dev/null   
$ python -c 'from importlib.metadata import version; print(version("searvey"))'
0.3.5.post8.dev0+07ab9ed

Which means that the current master is 8 commits after the 0.3.5 tag.

Now the dirty shouldn't be there. It's probably has something to do with this line:

searvey/pyproject.toml

Line 74 in 07ab9ed

dirty = true

I will check it out.

[ocefpaf]

I guess that we could add something like this in init.py

+1

Importlib metadata is for devs. Users still rely on the recorded dunder version a lot.