Python packaging documentation feedback and discussion

I agree 100%. I’m about as far from a “packaging newcomer” as it’s possible to get, and yet I still regularly look for advice on how to set up a new project. Where do I go? Who is doing feature comparisons between packaging tools (the tools themselves aren’t!)? Where can I get views on more advanced things like how to set up automated releases of my project? Not necessarily simple “follow these steps and you’re done”, but “this tool works better if you prefer/need X, and this tool if you prefer/need Y”.

I don’t know about raw beginners (most raw beginners I’ve dealt with consider packaging their code for publication to be a distant dream, not a consideration for right now :slightly_smiling_face:) but it’s the intermediate users, with bolted-together but out of date and difficult to maintain workflows, who want “something better” but who may not even know what “better” could mean, that I think we are letting down. People who’ve used setuptools forever, but have heard that there are newer, better, tools and want to try them. But who can’t find any way (short of trying out all the alternatives, or spending days reading docs) of working out what’s best for them.

That’s a great summary. It should be in the docs somewhere!

I’m tempted to mention the Diátaxis framework here, but I suspect others know more about it than I do. But in the terms of that framework, you seem to be talking about tutorials, whereas I’m more concerned that we don’t have enough in the way of how-to guides and explanations (reference is where the tool-specific docs come in). “How to choose a build backend”, “how to set up automated documentation for your project”, “how to automatically deploy yourt project”, “an explanation of task runners, and how they should be used”. That sort of thing.

I’ve just skimmed the Scikit-HEP docs, and there’s a bunch of stuff like that in there. Could that be included in the PUG? If not, then it would be informative to understand why not.

2 Likes