[Request] Package documentation link(s)

[stantond]

I'm following up this issue on ReadTheDocs about browsing docs offline with 3rd party apps - it looks like no one asked anyone here for help, but the issue is still outstanding.

There's currently no way to map from here to documentation in a format other applications can use. Details of why this would be useful are in the above ticket, but essentially there are examples of documentation names being different to the package names.

pypi-legacy accepts three URLs from a user, Home page, Download URL and Bugtrack url. warehouse only takes url, meant for the homepage.

Is there room for optional documentation URLs (plural as docs may be in multiple places and a user can choose which they prefer)?

Also on pypi-legacy here, as I'm not sure if this would be applied to pypi-legacy or kept for warehouse.

[dstufft]

Well warehouse takes Home page and download URL both currently. Both Warehouse and legacy also support arbitrary "Project URLs" which are essentially Name: URL pairs like: "Documentation", "https://docs.pypi.org/", however setuptools doesn't currently expose a way to add those.

[stantond]

I may be wrong, but I think leaving it to a custom Project URL means developers won't include a documentation URL - there's no habit formed for including docs in Legacy, and there's no field there to serve as a reminder or indication that this could now be done, so few will know to, and even if they do it's still very easy to forget.

Also, @ewdurbin is happy to do this on Legacy, but if you decide a Product URL covers this then I don't think that can be done with Legacy.

What do you think?

[fungi]

I've proposed setuptools support for Project-URL metadata at pypa/setuptools#1205 though my uploads to testpypi don't put the links anywhere obvious and the PKG-INFO link seems to present a munged metadata set with the Project-URL list stripped out (if you download the files however you can see it's present in both mudpy-0.0.1.dev231.dist-info/METADATA and mudpy-0.0.1.dev231/PKG-INFO files therein):

https://test.pypi.org/project/mudpy/
https://testpypi.python.org/pypi/mudpy/

The pkginfo library is able to find it in distributions downloaded from testpypi:

>>> pkginfo.SDist('mudpy-0.0.1.dev231.tar.gz').project_urls
[u'Bug Tracker, http://mudpy.org/contact/ Documentation, http://mudpy.org/documentation/ Source Code, http://mudpy.org/gitweb/mudpy.git']

The format of the list also seems to match the core metadata spec which in turn matches the design from PEP 345, so I'm not sure if I'm missing something or whether there's a bug in warehouse/cheeseshop.

[dstufft]

There might be missing support for it, though I thought I added it.

[fungi]

Ahh, pouring back over the specs, I believe I've misinterpreted the described format. Multi-use means multiple lines beginning with "Project-URL:" rather than one with multiple indented Title,URL pairs on distinct lines. I'll rejigger the PR and do another test soon.

[fungi]

The respun Project-URL support for setuptools is now up for review as pypa/setuptools#1210 and it's working for https://testpypi.python.org/pypi/mudpy/0.0.1.dev232/ but https://test.pypi.org/project/mudpy/0.0.1.dev232/ doesn't seem to provide the same links... leading me to suspect that implementation in Warehouse is not yet completed?

[ronaldoussoren]

FWIW. I've the same problem with PyObjC: The wheels contain "Project-URL" metadata, but that doesn't show up on warehouse while pkginfo can extract the information.

[di]

This was fixed in #2813, and should now be working:

If you're not seeing it yet, you may need to purge the cache for a given page:

$ curl -XPURGE https://pypi.org/project/<project name>/

[fungi]

Confirmed, my earlier test at https://test.pypi.org/project/mudpy/0.0.1.dev232/ is now showing them as intended (generated via the recent support included by Setuptools 38.3.0 and PBR master branch slated for whatever release follows 3.1.1).

[ronaldoussoren]

Same here, this now works for my projects.

Thank you!