Consistent formatting across pip's documentation

[pradyunsg]

Mostly to make my life easier as I start spending more time in this part of the codebase.

This PR will make git blame for our documentation slightly worse, but I'd much rather spend less time figuring out what symbol I'm supposed to use for a heading in a certain file + whether I should put an empty line in certain spots.

I'm trying to write all of these things down into a "conventions" document, WIP for which is here: https://github.com/pradyunsg/pip/blob/docs/conventions/docs/html/development/conventions.rst

[pradyunsg]

If someone could take a look at this (and the supporting draft PR, which needs more work; and is most independent of this change), that'd be great!

[pfmoore]

In general this looks fine to me. I haven't checked that you do use the heading markers consistently, but it's certainly more consistent than it was, and when you land the style guide we can fix any further deviations incrementally.

I really dislike the "always use lowercase for pip" convention. I'd much rather we treated pip like a conventional noun (capitalise at the start of sentences) but if consensus is against me I'll survive. And while many of the changes here are related to that rule, I'd rather we had that debate independently and not as review comments on this PR - so I'm not going to block this PR on that point, but I would suggest that we open a separate "pip branding" discussion to cover it (it might also be nice to ask for submissions for a "pip logo" as part of that conversation 🙂).

[pradyunsg]

we open a separate "pip branding" discussion to cover it (it might also be nice to ask for submissions for a "pip logo" as part of that conversation 🙂).

Yeas. :)

[uranusjr]

@pradyunsg Didn’t we discover a while ago pip somehow has a logo?

[pradyunsg]

@uranusjr I don't recall, sorry. 🙈

[xavfernandez]

There is this one that appears from time to time but I could not find an official source.

[uranusjr]

Yup, that’s the one I was thinking about. The logo appears if you search for pip in Google, but I have no idea where they picked this up. Probably some tutorial invented it and people just assumed it’s correct because Google says so.

[pfmoore]

Meh, that's a bit bland IMO. I was sort of hoping someone creative could come up with something with a cartoon snake in it 🙂 🐍

A snake's head peering out of a cardboard box, for packaging Pythons? This one's grabbed from a Google search and certainly copyright, but is the sort of thing I had in mind...

[hugovk]

Reminds me a bit of Coverage.py's Sleepy snake :)

https://nedbatchelder.com/blog/201912/sleepy_snake.html

[pfmoore]

Yeah, I wonder if @nedbat's son would be willing to do a logo for us?

[anudit]

Whipped up a couple of ideas. @pradyunsg @uranusjr @pfmoore

[ei8fdb]

Logo

Just saw this issue. I'd like to suggest posting the request for a logo to the Open Source Design jobs board. We (Open Source Design) run a jobs board for lots of different types of design work - logo design included.

You can do it here: https://opensourcedesign.net/jobs/job-form/

The way things usually go are: an interested designer will pick up the job post. They'll have some questions about brief, etc.

I won't be doing the design work - I'm a terrible logo designer - but I'm happy to be a/the contact person for this design.

If this is a good idea, before it gets posted, I'd suggest we have a short discussion on creating a design brief. It could be a nice community activity to get inspiration from the pip (maybe wider python?) community about pip is to them.

Thoughts?

Disclosure: I'm one of the Open Source Design core members.

[pradyunsg]

I'm gonna go ahead and eagerly lock this issue -- please comment on #7793 for pip branding things! ^>^