Add build clarification to package guide

[lwasser]

closes #74

This page has been reviewed by several folks including @arianesasso @isabelizimm and was written based upon issue #74
open for review now and will hope to merge in early september. @jagerber48 hoping this provides clarification!

---

• To see the specific tasks where the Asana app for GitHub is being used, see below:
  • https://app.asana.com/0/0/1205483903824141

[NickleDave]

This looks great and is 95% of the way towards answering the question of "what is building a Python package".

I added a couple of comments about how maybe we could make the link between "build" and "distribution package" more explicit. I think we added all the info we need but it could possibly be presented more directly, so the text links in to the excellent diagram.

I also left a comment about how we will link to these sections and how we expect readers to find them. I'm afraid that might have been discussed at the meeting I missed so sorry if I'm just adding noise.

I haven't made minor typo edits, will try to come back for those later.

Will be great to have this added to the guide.

[NickleDave]

This diagram is great! It captures the key ideas we need to convey here

I'm confused about why we show documentation going into the build distribution though? None of the tree diagrams below show documentation in the sdist or wheel

[lwasser]

oh interesting! my lens was a bit different. i was that as just a bucket of packaging "things" and then you build. not "these are the things that go into the dist" BUT your comment makes sense that most people would see that as documentation going into the build. so we can revice that graphic to just say package code, metadata (and optionally?? tests) given it's all about publishing!! and maybe i have a docs arrow that goes to a website bubble??

i know the test thing is really controversial and it turns out this controversy is not just in our ecosystem!!

[lwasser]

What do you think about this? i don't want to make this graphic too complex but essentially there are some different things that could go into those SDists vs wheels. i suspect that will get confusing for newer maintainers however.

[NickleDave]

This first sentence might come off as a little confusing for a couple reasons:

• we have not explicitly made the link (yet, on this page) between "building" a package and "publishing" it
• the first sentence in particular might sound like it's talking about how we organize source code, especially if a reader doesn't already understand what is meant by metadata
• even in the next sentence, we still haven't "admitted" that when we say "specific organization and structure", we mean a distribution package that has been built--the reader doesn't find this out until the end of the paragraph.

I would strongly suggest we directly answer the question posed by the heading, and then say the rest. Something like this:

To [publish your Python package](link to publishing page) and make it easy for anyone to install, you first need to build it. What does it mean to build a Python package? [As shown above](link to figure), when you build your Python package, you convert the source files into something called a distribution package. (Confusingly, the term package is overloaded in Python and many other languages, so on this page, we adapt the convention of the Python Packaging Authority and refer to the product of the build step as a distribution package). A distribution package contains your source code and metadata about the package, in the format required by the Python Package Index, so that it can be installed by tools like pip...

[lwasser]

this has been fixed and pushed here @NickleDave thank you for the suggestion. I think @jagerber48 actually was getting at a similar thing where i wasn't linking building to publishing which is what a user cares about. i hope the text is better overall now.

[NickleDave]

Commenting here because I'm not sure where else to put it -- how do we expect a reader to get to this section? Is the entire "Packaging" section meant to be read consecutively? Do we also want to cater to readers that are looking for specific information?

• If we want to cater to readers looking for specific information
  • should there be a direct link to this page from the intro page?
  • should the title be "what is building a python package?" -- if someone doesn't know the terms "source and wheel distributions" then they might not click on this page, because they won't understand why they need to know what those are
  • if the goal is for the sections to also be read consecutively, should we have a sort of "flow" on the intro page that links to each section? I feel like it's really easy to miss the "next section" links on the bottom of pages, although that's maybe my particular ADHD

[lwasser]

excellent question @NickleDave i think because the guide has evolved, the organization may need to change. i don't want to expect anyone to read it consecutively as i know better - human behavior on websites is all about search, find what you need and keep it moving! so we want to have a navigation that supports that common use case and surface information as much as possible. in the docs section we have a bunch of individual smaller pages. we could break this up too or just as you mention surface via links. i'm really open to what you think would be best for that intended usecase (supporting people finding what they need)

[lwasser]

ok david - i definitely renamed the page.

Learn about Building a Python Package

i ive also integrated your edits!! but what i don't know is where you want links to go!! i think a flow would be good. do you mean the intro page for this specific section. and then maybe number them and explain what is on each?

Right now, the intro page for this section looks like this:

it would be simple to add a numbered flow.i'll try that now and show you since we're in spatial chat together and you don't know - yet - that i'm pinging you here 😆

[lwasser]

Is this what you had in mind?? if not just let me know. i can style it more interestingly in the future as well - or maybe we move from sphinx altogether for prettier docs in the future...

[lwasser]

ok @NickleDave i've addressed all of your comments (i think). so let me know if you catch anything else OR if things are still not addressed correctly! i wasn't sure about the intro page comment and whether i got what you were looking for!!

[lwasser]

@all-contributors please add @merwok for code, review

[allcontributors]

@lwasser

I've put up a pull request to add @merwok! 🎉

[lwasser]

hey there @merwok I wanted to thank you for more great / helpful feedback on our guide. If you are interested in joining our discussions on packaging in slack, we'd welcome you there!! you can email me at leah at pyopensci.org and i can provide a link or you can provide me with your email some other way. If you have too many slacks / packaging conversations i totally understand that as well. i just wanted to extend the offer given you've been so helpful here already!

[merwok]

I am not using slack outside of work, but feel free to tag me on github for anything where I could help!

[lwasser]

I am not using slack outside of work, but feel free to tag me on github for anything where I could help!

Thank you @merwok i will !! i really appreciate all of your feedback here!!

[lwasser]

ok colleagues - i think i've addressed all of the issues / comments above at this point.

I'd love to get this merged by next week on October 31. If you have a few moments to have a look at the final changes, please do so and leave any last comments.

If not, you can ignore and things will be merged as is next week on the 31!
If you don't have time to review but still have feedback , you can always open an issue and we can work together to get the text right / more clear together some more.

Thank you everyone for all of the feedback and again if something is still wrong / confusing i'm super open to making more changes be it this week / early next or in another PR.

[lwasser]

ok y'all!! i'm excited to merge this once ci finishes here! thank you all again for the input on this pr. i think once we couple this information with our tutorials we will have some great beginner-friendly / non python packaging expert friendly content!!