This related thread might be of interest: What new Reference or Explanation would usefully reduce confusion? It suggests a few specific document topics which might address the confusion which this topic reports.
1 Like
Cameron, I just took a look at PyPA The Missing Outline. Some suggestions:
- Suggest you reformat your 13 April message to make the link clickable. (Probably indent with quoting (’>’) instead of with unformatted code (three backticks ‘```’.)
- I like the Diàtaxis framework for technical documentation. It seems you are writing what they call a “How-To Guide”. Consider using their framework to sharpen your focus. Be clear on the audience and the goal. Avoid sliding into Tutorial or Reference or Explanation.
- There is another way to “publish a package”, which is by making it a self-contained command-line executable, which need not be installed to the user’s Python environment, and treats the user’s Python interpreter as a runtime platform. You don’t intend to cover this, but it would be helpful to say in the first section that you don’t intend to. Deflect the readers who actually want a Guide to Packaging a Command-Line Executable.
- In “The Build System”, it might be helpful to state that “build” in this context is limited to the Source Distribution and Wheel artifacts, and does not apply to other artifacts which one might “build”: command-line executables, documentation, etc.
I hope this is helpful for you. Thank you for the writing!
Two more comments on your draft, having thought some more.
- Consider a more specific title than PyPA The Missing Outline. You are giving instructions for ending up with sdist/wheel artifacts, and uploading to PyPI. So maybe include these terms in your title. Also, what happens when PyPA fills in their missing outline? You will still have a useful guide, but your title will not make so much more sense.
- I think I want to attempt a Guide to Packaging a Python Application File, based on using shiv, pez, and zipapp. I think it will be parallel in audience and intent and structure to yours. When I have a draft, we can compare them.
I feel exactly the same. I’m lost and am going to stick with setup.py until a benevolent dictator wakes up and cleans the packaging mess up.
3 Likes
Just FYI, since somehow I never got back to John:
- Diàtaxis: this doc is an Explaination, not a Tutorial. It aims to provide the mental framework on which any publish-to-PyPI How To would hang in an author’s mind.
- The PyPA people were very welcoming, and after some review my doc is up on the site at: The Packaging Flow — Python Packaging User Guide
- Your intended guide would be a tool specific How To.
2 posts were split to a new topic: Help with my pyproject.toml