[Distutils] on integrated docs in Warehouse and PyPI

[Jason R. Coombs]

I had some thoughts on documentation integration (and its deprecation in Warehouse), which I wrote up here: https://paper.dropbox.com/doc/Integrated-Docs-is-an-Essential-Feature-HEqnF8iWzCFwkCDaz0p8t

I include the full text below for ease of access and response.

Yesterday, as I was migrating Setuptools from PyPI to Warehouse due to this issue<https://github.com/pypa/setuptools/issues/589>, Donald alerted me to the fact that Warehouse does not plan to support documentation hosting<https://github.com/pypa/setuptools/issues/604#issuecomment-223614048>, and as a result, integrated documentation for the packaging infrastructure is deprecated.

At first blush, this decision seems like a sound one - decouple independent operations and allow a mature, established organization like RTD<https://readthedocs.org/> to support and manage Python Package documentation. I have nothing but respect for RTD; I reference them here only as the prime example of a third-party doc hosting solution.

After spending most of a day working on getting just one project documentation (mostly) moved from PyPI to RTD, I’ve realized there are several shortcomings with this approach. Integrated hosting provides several benefits not offered by RTD:


  *   Uniform custody - the person or team that owns/maintains the package also owns/maintains the documentation with a single point of management and authorization.
  *   Shared credentials - the accounts used to administer the packages are re-used to authenticate authorized users to the documentation. RTD requires a separate set of accounts for each user involved with the documentation.
  *   Shared naming - a name registered as a package is automatically reserved for the documentation.
  *   Automatic linkage - PyPI provides a Package Documentation link on each package that has documentation.
  *   Control over the build process - although RTD does provide excellent hooks for customization and control, the process is essentially out of the hands of the operator. Thus when issues like this<https://github.com/rtfd/readthedocs.org/issues/2254> arise (probably rarely), the user is at the mercy of the system. With PyPI hosting, it was possible to manually build and upload docs when necessary and to control every aspect of the build process, including platform, Python version, etc.
  *   One obvious choice - although RTD today is the obvious choice for hosting, I can see other prominent alternatives - using Github pages or self hosting or perhaps another service will emerge that’s more integrated with the packaging process. Having a sanctioned, integrated documentation hosting gives users confidence that it’s at least a good default choice if not the best one.
  *   API access - Although RTD hopes to provide support for project creation through an API, it currently only allows querying through the public API. Therefore, it’s not feasible through tools to mechanically configure projects in RTD. Each project has to be manually configured and administered.

For me, this last limitation is the most onerous. I maintain dozens of projects, many of them in collaboration with other teams, and in many of those, I rely on a model implementation<https://github.com/jaraco/skeleton> that leverages PyPI hosting as part of the package release process to publish documentation. Moving each of these projects to another hosting service would require the manual creation and configuration of another project for each. As I consider the effort it would take to port all of these projects and maintain them in a new infrastructure, I’m inclined to drop documentation support for all but the most prominent projects.

The linkage provided by PyPI was a most welcome feature, and I’m really sad to see it go. I’d be willing to give up item 5 (Control) if the other items could be addressed.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/distutils-sig/attachments/20160604/ac46e865/attachment-0001.html>