Provide separate development and documentation URLs in PyPI metadata?
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 😉.)
On 2017 Jun 24, at 13:34, Brett Cannon brett@python.org 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
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'. 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
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.
Sent from my iPhone
On Jun 24, 2017, at 1:48 PM, Thomas Kluyver thomas@kluyver.me.uk wrote:
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'.
On Sat, Jun 24, 2017, 10:51 Donald Stufft, donald@stufft.io 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 sounds reasonable toe if the flexible, general case is going to be supported.
-Brett
Sent from my iPhone
On Jun 24, 2017, at 1:48 PM, Thomas Kluyver thomas@kluyver.me.uk
wrote:
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'.
Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig
On 25 June 2017 at 03:51, Donald Stufft donald@stufft.io 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.
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 Tue, Jun 27, 2017, at 04:58 PM, 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.
Perhaps this points to labelling URLs with nouns rather than verbs: things like 'mailing list', 'source code' or 'issue tracker' seem less ambiguous than 'participate' or 'contribute'.
Thomas
On Tue, 27 Jun 2017 at 10:06 Thomas Kluyver thomas@kluyver.me.uk wrote:
On Tue, Jun 27, 2017, at 04:58 PM, 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.
Perhaps this points to labelling URLs with nouns rather than verbs: things like 'mailing list', 'source code' or 'issue tracker' seem less ambiguous than 'participate' or 'contribute'.
I agree with Thomas on this one. Seeing a link that says "Participate" just feels like it's missing an exclamation point and subtext saying I could earn $2,000/week from it. ;)
Since this has turned into bikeshedding over names when we have a general metadata solution, I've filed https://github.com/takluyver/flit/issues/116 and consider my question answered. :)
On 28 June 2017 at 01:58, Barry Warsaw barry@python.org 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.
On Sat, Jun 24, 2017, 10:49 Thomas Kluyver, thomas@kluyver.me.uk 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
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 brett@python.org 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 Jun 24, 2017, at 05:34 PM, Brett Cannon wrote:
So my question/idea is if it would make sense to have separate, explicit development and documentation URLs in the PyPI metadata?
Wholehearted +1
I already use PyPI as the first stop for finding out about a library or Python project. I have a nice Chrome search shortcut to do a search, and once I've found the PyPI page I have a much greater chance of finding a link to upstream. Regardless of whether that points to the development site or the documentation site, I can usually find a way back to the other one.
Still, I'd love for it to be much more explicit.
I also think pythonhosted should be deprecated if it's not already. It's kind of more of a pain than useful these days.
Cheers, -Barry
participants (6)
-
Barry Warsaw -
Brett Cannon -
Donald Stufft -
John Thorvald Wodder II -
Nick Coghlan -
Thomas Kluyver