On 2017 Jun 24, at 13:34, Brett Cannon wrote:

When you go to PyPI.org for a project you will find a link to the "homepage". Now for some projects that's their development site, e.g. GitHub URL. For others it's their documentation site, e.g. Read the Docs. And not all projects link to both from their PyPI page (e.g. yesterday I noticed flit didn't directly link to its doc site, although Thomas fixed this when I pointed it out).

So my question/idea is if it would make sense to have separate, explicit development and documentation URLs in the PyPI metadata? For me that would make a project's PyPI page a true homepage as I would know that no matter what I could find where it's developed or where the docs are by going to PyPI. This compares to now where either I gamble and go to PyPI in hopes the developer provided the link there or hope I craft the right search on Google (which based on my search yesterday for [Sphinx makefile] shows I don't always succeed at).

The package data exposed by PyPI's JSON and XML-RPC APIs already includes a "docs_url" field; however, this seems to only ever be set for projects whose documentation is on http://pythonhosted.org with no way to point it to other domains. PEP 345 defines a Project-URL field[1] that could be used to tell PyPI where documentation is hosted, but I'm not aware of a single tool that does anything with or even lets you set that field. [1]: https://www.python.org/dev/peps/pep-0345/#project-url-multiple-use

PyPI supports arbitrary key => URL mappings called project urls. The best way to implement this is probably to expose that feature with maybe some recommended keys to use (to avoid docs vs documentation fracture etc). As far as I know disutils2 was the only thing to ever support them. Sent from my iPhone

On Jun 24, 2017, at 1:34 PM, Brett Cannon wrote:

When you go to PyPI.org for a project you will find a link to the "homepage". Now for some projects that's their development site, e.g. GitHub URL. For others it's their documentation site, e.g. Read the Docs. And not all projects link to both from their PyPI page (e.g. yesterday I noticed flit didn't directly link to its doc site, although Thomas fixed this when I pointed it out).

So my question/idea is if it would make sense to have separate, explicit development and documentation URLs in the PyPI metadata? For me that would make a project's PyPI page a true homepage as I would know that no matter what I could find where it's developed or where the docs are by going to PyPI. This compares to now where either I gamble and go to PyPI in hopes the developer provided the link there or hope I craft the right search on Google (which based on my search yesterday for [Sphinx makefile] shows I don't always succeed at).

Anyway, just an idea I had based on my flit experience yesterday plus a tweet sent to me. (And if PyPI already supports this somehow then Thomas should brace for the feature request from me 😉.) _______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig

On Sat, Jun 24, 2017, 10:49 Thomas Kluyver, wrote:

On Sat, Jun 24, 2017, at 06:34 PM, Brett Cannon wrote:

Anyway, just an idea I had based on my flit experience yesterday plus a tweet sent to me. (And if PyPI already supports this somehow then Thomas should brace for the feature request from me 😉.)

This prompted me to go and look at the metadata PEPs. I thought the URL fields were only 'Home-Page' and 'Download-URL', but in fact PEP 345 added a multi-use 'Project-URL' field:

https://www.python.org/dev/peps/pep-0345/#project-url-multiple-use

I quite like this idea - rather than prescribing a couple of specific kinds of URL, it lets the project author list as many as make sense. Perhaps we should recommend a set of common labels for URLs in this field, e.g. 'Documentation', 'Bug tracker', 'Source repository'.

In flit's case it could have some reasonable set of defaults supported in the metadata section and then have a more general "URLs" section that's more free-form. -brett

This does leave open the question of which one to put in the mandatory 'Home-Page' field (I usually use the address of the repo), and whether to duplicate it in a 'Project-URL'.

Thomas _______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig

On 25 June 2017 at 03:51, Donald Stufft wrote:

It's only kind of mandatory. The spec says it is but nothing fails IIRC if you omit it. Perhaps we should just deprecate it and move everything to project urls.

That's the direction I was going in PEP 426/459: https://www.python.org/dev/peps/pep-0459/#project-urls The two missing pieces I now see would be recommended tags for "Participate" and "Funding" URLs. I'd favour "Participate" over any variant of "Contribute", as without context, "Contribute" makes me think of financial support in the crowdfunding/tip jar sense. "Funding" is general enough to be suitable for crowdfunding/tip jar links, freelancing/contracting links, and links to employer/sponsor open source info pages. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia

On Jun 25, 2017, at 11:33 AM, Nick Coghlan wrote:

I'd favour "Participate" over any variant of "Contribute", as without context, "Contribute" makes me think of financial support in the crowdfunding/tip jar sense.

"Participate" may mean two different things. * Here's the development home, with a repo and issue tracker, contributions welcome! * Here's the mailing list or other forum where we discuss the future of Guido's Magical Mystery Time Machine. It would be nice to be able to capture both meanings. -Barry

On 28 June 2017 at 01:58, Barry Warsaw wrote:

On Jun 25, 2017, at 11:33 AM, Nick Coghlan wrote:

...

I'd favour "Participate" over any variant of "Contribute", as without context, "Contribute" makes me think of financial support in the crowdfunding/tip jar sense.

"Participate" may mean two different things.

* Here's the development home, with a repo and issue tracker, contributions welcome!

* Here's the mailing list or other forum where we discuss the future of Guido's Magical Mystery Time Machine.

It would be nice to be able to capture both meanings.

This isn't feasible to capture generically, since projects have so many different approaches to communication. 1. A lot of modern projects *only* have their repo & issue tracker, with no other dedicated discussion or help forum (with sites like Stack Overflow handling requests for help) 2. Bigger projects will have *multiple* venues for communication, usually including at least one near-real-time channel (e.g. IRC, Slack, Gitter), and one more asynchronous one (e.g. a mailing list or web forum) So the only generic reader-centric (rather than publisher-centric) distinctions we can reliably make are: * "I want to use this project, tell me how" (aka "Documentation") * "I want to participate in the design and development of this project, tell me how" (aka "Participate") * "I want to help fund the design and development of this project, tell me how" (aka "Funding") That doesn't preclude having other more specific links (e.g. the PEP 459 draft also proposes "Home", "Repository" and "Tracker": https://www.python.org/dev/peps/pep-0459/#project-urls), it's just about reserving the "Documentation" tag primarily for user documentation rather than contributor documentation. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia