Skip to content

Can the Python Package Tools Decision Diagram be simplified #489

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ucodery opened this issue May 15, 2025 · 6 comments
Open

Can the Python Package Tools Decision Diagram be simplified #489

ucodery opened this issue May 15, 2025 · 6 comments
Labels
help wanted We welcome a contributor to work on this issue! thank you in advance!

Comments

@ucodery
Copy link
Collaborator

ucodery commented May 15, 2025

I recently revisited the decision diagram at https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-build-tools.html#tools-for-building-your-package and noticed that it seems to be more complicated than necessary.

Specifically, the check "Does my package have a few c/c++ extensions?" does not seem to provide any value. Both paths suggest the same front-end and back-end choices.

I am also confused why the Build tool is called out. It has ** on two of the mentions, * on another, but I don't see any footnotes in the diagram or on the page.

Finally, while I am here I also want to make a soft recommendation that tool suggestions only be given on terminal tree nodes, as is required in a traditional decision tree.

@sneakers-the-rat
Copy link
Contributor

+1 that all makes sense.

Another way to simplify could be to have a "fast exit" branch in the decision tree that's like "i just want you to tell me what to use -> hatch" or something

@lwasser
Copy link
Member

lwasser commented May 19, 2025

I'm happy to support a simpler version of that diagram. Could we use Mermaid or something easier for others to edit? Right now, it's an AI / svg / pdf file. I'm happy to share that too... whatever y'all think.

NOTE: today in our open space we got a lot of feedback that we should update the packaging guide to reflect the current state of tools. This means also mentioning UV. not related to this diagram --- yet, but related to some of the other issues opened.

@ucodery
Copy link
Collaborator Author

ucodery commented May 19, 2025

While I do like mermaid, and it might make it easier to remotely collaborate on graphics like this, I believe we would have to adopt a new sphinx plugin to use it on the site. Which is doable. The other downside would be loosing most of that great design. With mermaid, we could set the colours to match the rest of the sight, but that would be about where the branding would have to stop.

@lwasser
Copy link
Member

lwasser commented Jun 10, 2025

Ok no problem. How about I move the file from Adobe to an inscape compatible SVG version? We could then host it either here or we could host versions of it on zenodo instead

I have been fighting with mermaid for another diagram! it's pretty hard to make it look readable. So maybe svg is best.
I'll open a PR here now. I'm also happy to make edits to the diagram as we need them.

I wish it was in canva. maybe that is a future thing I can work on for easier remote editing.

@lwasser
Copy link
Member

lwasser commented Jun 10, 2025

#518 added svg and instructions / fonts etc

@lwasser
Copy link
Member

lwasser commented Jun 10, 2025

Ok - have a look at this link. I made a copy of the diagram and we can edit it there. I can add anyone to the file who wants to take a stab at edits OR you should be able to comment on the file too. let's update it to meet our current needs. it hasn't been updated in exactly a year!

Canva Diagram

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
help wanted We welcome a contributor to work on this issue! thank you in advance!
Projects
Status: No status
Development

No branches or pull requests

3 participants