Improve uv instructions, add dev dependencies

[mgeier]

This arguably simplifies the usage of uv by not suggesting to use uv pip at all, but instead creating a local pyproject.toml file.

This avoids having to remember to activate virtual environments. The uv run commands do that automatically.

This workflow is still new to me, so it would be good if you could check if everything actually works for you locally, @fs446!

I've also added a somewhat minimal script file for our users to get started, but maybe this can be improved?
It would be good if it could be more concise, but it should also do something meaningful ...

[mgeier]

I had to do some trial and error to get the readthedocs build going. I have squashed my attempts into one commit again.

Here are the rendered instructions:

https://sfs-python--187.org.readthedocs.build/en/187/installation.html

https://sfs-python--187.org.readthedocs.build/en/187/contributing.html

[fs446]

Works nicely on my Mac.

I would be fine with the currently proposed minimal script file at
https://sfs-python--187.org.readthedocs.build/en/187/installation.html.
Maybe it is useful to have a hint on the example section? Maybe it is useful to provide a Jupyter notebook example handling as well?

Is the Editable Installation section at
https://sfs-python--187.org.readthedocs.build/en/187/contributing.html
also a useful section at
https://sfs-python--187.org.readthedocs.build/en/187/installation.html
? There seems to be two workflows we should address:

1. installing AND editable working -> make this information available in installation section
2. installing AND editable working AND contributing -> make this information in contributing section

[mgeier]

I found out that --editable on its own creates a so-called "workspace", but that's not what we want in this case (because that would use a combined lock file and not update ours). I added --no-workspace in a1efe78 to avoid this.

Maybe it is useful to have a hint on the example section?

I have added a sentence in 7139d08, is that enough?

Maybe it is useful to provide a Jupyter notebook example handling as well?

I'm not sure how. How would you use it?

I have already mentioned uv run jupyter lab, what else should I add?

There seems to be two workflows we should address:

1. installing AND editable working -> make this information available in installation section

2. installing AND editable working AND contributing -> make this information in contributing section

I don't think those should be the options ... why would you need "editable" in the first workflow?

I think it should be:

1. the default and obvious way, just using released versions: install sfs from PyPI (without needing to know what that is). No Git, no GitHub, no dev dependencies.
2. using non-released versions (and optionally contributing): git clone is necessary, "editable" is the only thing that makes sense, dev dependencies are installed.

There is actually a third way, "installing from a Git branch via URL, no local git clone, no dev dependencies", but I don't think we need to mention this.

[mgeier]

Even though I think everyone should use uv for their own good, we shouldn't create the impression that it is the only way. I've added b6ea662 to hopefully make this clear.

[fs446]

I found out that --editable on its own creates a so-called "workspace", but that's not what we want in this case (because that would use a combined lock file and not update ours). I added --no-workspace in a1efe78 to avoid this.

Maybe it is useful to have a hint on the example section?

I have added a sentence in 7139d08, is that enough?

Maybe it is useful to provide a Jupyter notebook example handling as well?

I'm not sure how. How would you use it?

I have already mentioned uv run jupyter lab, what else should I add?

Forget about my hasty proposal, it indeed makes no sense. The hint is fine and people can look into the examples, which actually are notebooks.

There seems to be two workflows we should address:

1. installing AND editable working -> make this information available in installation section
2. installing AND editable working AND contributing -> make this information in contributing section

I don't think those should be the options ... why would you need "editable" in the first workflow?

I think it should be:

1. the default and obvious way, just using released versions: install sfs from PyPI (without needing to know what that is). No Git, no GitHub, no dev dependencies.
2. using non-released versions (and optionally contributing): git clone is necessary, "editable" is the only thing that makes sense, dev dependencies are installed.

There is actually a third way, "installing from a Git branch via URL, no local git clone, no dev dependencies", but I don't think we need to mention this.

The third way is probably not to mention, people doing this probably know what they are up to.
The second way (2. in your ordering) is the handling I had in mind with 1. in my ordering. It is a valid workflow that people actually get the toolbox via git clone, make it editable, modify stuff to do their stuff and never contribute (which is sad, but ok). Again, people that want to use the toolbox that way, probably figure that some information about git cloning / editable version is then found at the contributing section.

[fs446]

Even though I think everyone should use uv for their own good, we shouldn't create the impression that it is the only way. I've added b6ea662 to hopefully make this clear.

Yeah, that's nice.

[fs446]

IMO ready to push