[Distutils] on integrated docs in Warehouse and PyPI

[Nick Coghlan]

On 5 Jun 2016 2:18 am, "Ralf Gommers" <ralf.gommers at gmail.com> wrote:
>
>
>
> On Sun, Jun 5, 2016 at 6:33 AM, Nick Coghlan <ncoghlan at gmail.com> wrote:
>>
>>
>> On 4 Jun 2016 6:54 am, "Donald Stufft" <donald at stufft.io> wrote:
>> >
>> >
>> >> On Jun 4, 2016, at 9:33 AM, Nathaniel Smith <njs at pobox.com> wrote:
>> >>
>> >> I think everyone would agree that having some nice doc hosting
service available as an option would be, well, nice. Everyone likes
options. But the current doc hosting is unpopular and feature poor, falls
outside of the PyPI core mission, and is redundant with other more popular
services, at a time when the PyPI developers are struggling to maintain
core services.
>> >
>> >
>> >
>> > To add to what Nathaniel said here, there are a few problems with the
current situation:
>> >
>> > Documentation hosting largely worked “OK” when it was just writing
files out to disk, however we’ve since removed all use of the local disk
(so that we can scale past 1 machine) and we’re now storing things in S3.
This makes documentation hosting particularly expensive in terms of API
calls because we need to do expensive list key operations to discover which
files exist (versus package files where we have a database full of files).
>>
>> Amazon do offer higher level alternatives like
https://aws.amazon.com/efs/ for use cases like PyPI's docs hosting that
assume they have access to a normal filesystem.
>>
>> Given the credential management benefits of integrated docs,
>
> From the RTD blog post linked by Nathaniel:
> ""
> Our proposed grant, for $48,000, is to build a separate instance that
integrates with the Python Package Index’s upcoming website, Warehouse.
This integration will provide automatic API reference documentation upon
package release, with authentication tied to PyPI and simple configuration
inside the distribution.
> ""
>>
>> it does seem worthwhile to me for the PSF to invest in a lowest common
denominator static file hosting capability,
>
> Seems like a very poor way to spend money and developer time imho. The
original post by Jason brings up a few shortcomings of RTD, but I'm amazed
that that leads multiple people here to conclude that starting a new doc
hosting effort is the right answer to that.

It isn't about funding a new idea, it's about keeping an existing solution
working rather than breaking it abruptly and forcing other time strapped
community volunteers to change how they do things immediately, or else
leave their users without documentation.

Since there's been zero previous discussion with distutils-sig or the PSF
Board regarding improving the integration of ReadTheDocs with PyPI, I had
absolutely no idea they had sought a grant from Mozilla to invest time in
improving that aspect of things.

Regards,
Nick
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/distutils-sig/attachments/20160605/93c741a3/attachment.html>