Simplify single source

[ChrisBarker-NOAA]

I'm no longer calling this a WIP -- I hope it's close to as good as it's going to get.

This is a follow-up to #1578 -- I made a mess of it when I tried to rebase.

The goal here is to have a simple, and not opinionated, page that guides folks to their build tool of choice's way to handle version strings.

Not sure if it's a guide or a discussion -- I put in discussion, but maybe it's more of a guide.

Now that I think about it -- if it's in discussions, then maybe it could be a lot longer, and go into why one might want to (or not want to) provide a version attribute in the importable package.

But I don't know that I want to moderate THAT discussion…

---

📚 Documentation preview 📚: https://python-packaging-user-guide--1580.org.readthedocs.build/en/1580/discussions/single-source-version/

[webknjaz]

@ChrisBarker-NOAA have you looked into the possibility of embedding a diagram? (#1276 (comment))
I think, it's important to demonstrate unidirectional flow of the version sourcing.

[ChrisBarker-NOAA]

OK -- I think this is in good shape, and has addressed the concerns of everyone.

Open Question: whether to include a diagram -- see: #1580 (comment)

Other than that -- good to go.

Editors -- anything else?

[webknjaz]

Open Question: whether to include a diagram -- see: #1580 (comment)

Thanks for acknowledging that you saw my request. What's your opinion? I don't think I saw you sharing it anywhere — have I missed it?

[bwoodsend]

What would the diagram contain? I'm guessing some flow that depicts pyproject.toml -> build backend -> project/__init__.py:__version__ -> version in package metadata? Not sure how I'd translate those into picture form short of just writing those words with rectangles round them.

[ChrisBarker-NOAA]

Open Question: whether to include a diagram --
What's your opinion?

I don't think it's necessary -- it's just not that complicated.

But I'm happy for the doc editor(s) to decide.

-CHB

[webknjaz]

@bwoodsend I made a diagram in this comment a while back: #1276 (comment). I imagined it'd be reused, maybe with some modifications. It's made with Mermaid.

@ChrisBarker-NOAA okay, I hear you. In the interest of unblocking the effort, I withdraw that request for now.

[flying-sheep]

Thanks for slogging through all our comments, I think the end result is really nice and clear now!

[ChrisBarker-NOAA]

Glad it got through to the end this time!

Thanks all -- it was a slog, but it's a much better document as a result of all the input.

[bwoodsend]

Here's to never seeing FileNotFoundError: .../site-packages/xyz/version.txt ever again!