on integrated docs in Warehouse and PyPI
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-HEqnF8... 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.
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. How do you propose to implement and support this hypothetical doc service, given PyPI's resource constraints? Who's going to implement and maintain it? What other features are you suggesting be de-prioritized so that people can focus on this instead? Opportunity cost is a real cost. (You might also be interested in this: http://blog.readthedocs.com/rtd-awarded-mozilla-open-source-support-grant/) -n On Jun 4, 2016 4:18 AM, "Jason R. Coombs" <jaraco@jaraco.com> wrote:
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-HEqnF8...
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.
_______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig
On Jun 4, 2016, at 9:33 AM, Nathaniel Smith <njs@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). On top of that, S3 is an eventually consistent store, while we have worked around this for package files (by changing the URL to include a hash of the file contents) this is not something that we can do for documentation. This means that while it will often be updated in a short time period, it could be hours and hours (or even days) for someone to see their uploaded documentation reflected on PyPI. I feel that the current documentation hosting is a bit of an attractive nuisance for people. It’s easy to get started with, but it lacks even basic features— features that I don’t have time to implement. This causes people to request these features be added and for me to have to tell them no (or to just ignore them) because I don’t have the time for it. I feel that people are going to be much better served using some mechanism whose core competency is this, then they are going to be by a barely supported feature on PyPI. If they’re using Sphinx they can use RTD and get powerful features like automatic building of the documentation on push, or if they like the “just upload a tarball” approach, they can get something similar with S3 on their own, or using Github pages, or Gitlab pages. So all in all, while I think there are some nice benefits of having this attached to PyPI, I think that we don’t currently have the resources to actually make it a good service, and I think it’s better to drop a badly supported service than it is to leave it there to take up time and effort of both PyPI maintainers, and for people using it not knowing that it’s barely supported. For what it’s worth, here’s the previous discussion on this topic https://mail.python.org/pipermail/distutils-sig/2015-May/026327.html <https://mail.python.org/pipermail/distutils-sig/2015-May/026327.html> — Donald Stufft
On 4 Jun 2016 6:54 am, "Donald Stufft" <donald@stufft.io> wrote:
On Jun 4, 2016, at 9:33 AM, Nathaniel Smith <njs@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, it does seem worthwhile to me for the PSF to invest in a lowest common denominator static file hosting capability, even if we also use the PyPI project admin pages to promote ReadTheDocs and the static site hosting offered by version control hosting companies. Regards, Nick.
Is this something that can be deferred until after the launch of warehouse? I am, personally, more interested in pypi features that are broken (because of the current codebase’s unmaintainability) that cannot be offloaded to other services than the ones that can be offloaded. From: Distutils-SIG [mailto:distutils-sig-bounces+tritium-list=sdamon.com@python.org] On Behalf Of Nick Coghlan Sent: Sunday, June 5, 2016 12:34 AM To: Donald Stufft <donald@stufft.io> Cc: DistUtils mailing list"" <distutils-sig@python.org> Subject: Re: [Distutils] on integrated docs in Warehouse and PyPI On 4 Jun 2016 6:54 am, "Donald Stufft" <donald@stufft.io <mailto:donald@stufft.io> > wrote:
On Jun 4, 2016, at 9:33 AM, Nathaniel Smith <njs@pobox.com <mailto:njs@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, it does seem worthwhile to me for the PSF to invest in a lowest common denominator static file hosting capability, even if we also use the PyPI project admin pages to promote ReadTheDocs and the static site hosting offered by version control hosting companies. Regards, Nick.
On Sun, Jun 5, 2016 at 6:33 AM, Nick Coghlan <ncoghlan@gmail.com> wrote:
On 4 Jun 2016 6:54 am, "Donald Stufft" <donald@stufft.io> wrote:
On Jun 4, 2016, at 9:33 AM, Nathaniel Smith <njs@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 <https://warehouse.python.org/>. 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. The much better alternative is: read the RTD contributing guide [1] and their plans for PyPI integration [2], then start helping out with adding those features to RTD. There is very little chance that a new effort as discussed here can come close to RTD, which is a quite active project with by now over 200 contributors. Starting a new project should be done for the right reasons: existing projects don't have and don't want to implement features you need, you have a better technical design, you want to reimplement to learn from it, etc. There are no such reasons here as far as I can tell. If there's money left for packaging related work, I'm sure we can think of better ways to spend it. First thoughts: - Accelerate PyPI integration plans for RTD - Accelerate work on Warehouse - Pay someone to review and merge distutils patches in the Python bug tracker Final thought: there's nothing wrong with distributed infrastructure for projects. A typical project today may have code hosting on GitHub or Bitbucket, use multiple CI providers in parallel, use a separate code coverage service, upload releases to PyPI, conda-forge and GitHub Releases, and host docs on RTD. Integrating doc hosting with PyPI doesn't change that picture really. Ralf [1] https://github.com/rtfd/readthedocs.org/blob/master/docs/contribute.rst [2] https://github.com/rtfd/readthedocs.org/issues/1957
On Sunday, June 5, 2016, Ralf Gommers <ralf.gommers@gmail.com> wrote:
On Sun, Jun 5, 2016 at 6:33 AM, Nick Coghlan <ncoghlan@gmail.com> wrote:
On 4 Jun 2016 6:54 am, "Donald Stufft" <donald@stufft.io> wrote:
On Jun 4, 2016, at 9:33 AM, Nathaniel Smith <njs@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 <https://warehouse.python.org/>. 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. The much better alternative is: read the RTD contributing guide [1] and their plans for PyPI integration [2], then start helping out with adding those features to RTD.
+1 RTD builds static HTML from Sphinx ReStructuredText and Commonmark Markdown IDK what the best way to do eg epydoc API docs (static HTML hosting) is w/ RTD. - cp into ./docs/_static/ before the RTD build? for GitHub Pages, I like ghp-import (which pushes a directory and a .nojekyll file to a fresh commit in a gh-pages branch). BitBucket Pages is a bit different. https://pypi.python.org/pypi/ghp-import I wrote a tool called 'pgs' (as a bottle app) which will serve static HTML from a git-branch (with pa/th -> pa/th.html redirection, too) but haven't yet spent the time to add proper git bindings, so the per-file process overhead is n (after browser (and potentially WSGI) caching) git branch static HTML support is not in scope for Warehouse because Warehouse doesnt do SCM. .. note:: | project.readthedocs.org URLs are now | project.readthedocs.io (Because cookie origins) http://blog.readthedocs.com/securing-subdomains/ One great feature of RTD, IMHO, is that you can host historical versions of the docs with stable versioned URLs like /en/v1.0.0/ (and a /en/latest/ redirect).
There is very little chance that a new effort as discussed here can come close to RTD, which is a quite active project with by now over 200 contributors. Starting a new project should be done for the right reasons: existing projects don't have and don't want to implement features you need, you have a better technical design, you want to reimplement to learn from it, etc. There are no such reasons here as far as I can tell.
If there's money left for packaging related work, I'm sure we can think of better ways to spend it. First thoughts: - Accelerate PyPI integration plans for RTD
- add a link to the Docs: in README.rst (long_description)?
- Accelerate work on Warehouse
- Pay someone to review and merge distutils patches in the Python bug
tracker
Final thought: there's nothing wrong with distributed infrastructure for projects. A typical project today may have code hosting on GitHub or Bitbucket, use multiple CI providers in parallel, use a separate code coverage service, upload releases to PyPI, conda-forge and GitHub Releases, and host docs on RTD. Integrating doc hosting with PyPI doesn't change that picture really.
+1 I like to include anchor-text-free links to all of these project links in the README.rst (and thus long_description) as RST inline blocks: [CI build badges] name ============ [description] | Wikipedia: `<https://()>`_ | Homepage: https:// | Docs: | Src: git | Src: hg | Build: | PyPI: | Warehouse: | Conda: | Conda-forge: ( #PEP426 JSONLD / Metadata 2.0 could, ideally, include these links as structured data; this is a very simple solution which works w/ GitHub, BitBucket, PyPI, Warehouse, RTD, and anything else that'll render README.rst. An RST DL definition list or just a list would be more semantically helpful than inline blocks, but less visual space efficient ... YMMV ) awesome-sphinxdoc is an outstanding resource for Sphinx (and thus RTD) things like themes: https://github.com/yoloseem/awesome-sphinxdoc/blob/master/README.rst#themes
Ralf
[1] https://github.com/rtfd/readthedocs.org/blob/master/docs/contribute.rst [2] https://github.com/rtfd/readthedocs.org/issues/1957
On 5 Jun 2016 2:18 am, "Ralf Gommers" <ralf.gommers@gmail.com> wrote:
On Sun, Jun 5, 2016 at 6:33 AM, Nick Coghlan <ncoghlan@gmail.com> wrote:
On 4 Jun 2016 6:54 am, "Donald Stufft" <donald@stufft.io> wrote:
On Jun 4, 2016, at 9:33 AM, Nathaniel Smith <njs@pobox.com> wrote:
I think everyone would agree that having some nice doc hosting
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
""
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
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. package release, with authentication tied to PyPI and simple configuration inside the distribution. 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
On Jun 5, 2016, at 6:04 PM, Nick Coghlan <ncoghlan@gmail.com> wrote:
On 5 Jun 2016 2:18 am, "Ralf Gommers" <ralf.gommers@gmail.com <mailto:ralf.gommers@gmail.com>> wrote:
On Sun, Jun 5, 2016 at 6:33 AM, Nick Coghlan <ncoghlan@gmail.com <mailto:ncoghlan@gmail.com>> wrote:
On 4 Jun 2016 6:54 am, "Donald Stufft" <donald@stufft.io <mailto:donald@stufft.io>> wrote:
On Jun 4, 2016, at 9:33 AM, Nathaniel Smith <njs@pobox.com <mailto:njs@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/ <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.
I mean “abruptly”. It was originally posted on distutils-sig just over a year ago with a relevant Warehouse issue at the same time [1]. In addition, we’re not deleting the capability to do it in legacy, just not adding it to Warehouse, so as we phase people over to Warehouse (like earlier I posted asking for folks to start opting in to using Warehouse) people will lose the ability to do this— but they’ll be able to go back and use legacy PyPI to regain it for as long as legacy PyPI is still running. We’re also going to switch the twine default (and the Python default) for uploads prior to legacy getting shut down. So essentially, we’re going to get a phased rollout with the ability to revert to the legacy behavior— at least until the legacy behavior is gone. The plan as indicated a year ago also says we’re not going to delete the existing documentation (since that requires zero ongoing effort to keep up, it’s just chucking things in a S3 bucket and forgetting about it) so their users won’t be without documentation, they’ll just be without *new* documentation until they come up with an alternative plan (after having it been phased in over time).
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.
There was some discussion on the Warehouse issues [1] and Eric had been talking to me on IRC about it for awhile too. Probably it would have been good to mention it on distutils-sig too, but just to be clear that RTD hadn’t done this in stealth mode :)
Regards, Nick
[1] https://github.com/pypa/warehouse/issues/509 <https://github.com/pypa/warehouse/issues/509> — Donald Stufft
On 5 Jun 2016 3:21 pm, "Donald Stufft" <donald@stufft.io> wrote:
On Jun 5, 2016, at 6:04 PM, Nick Coghlan <ncoghlan@gmail.com> wrote: 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.
There was some discussion on the Warehouse issues [1] and Eric had been
talking to me on IRC about it for awhile too. Probably it would have been good to mention it on distutils-sig too, but just to be clear that RTD hadn’t done this in stealth mode :) Yeah, with the additional info about RTD's Mozilla grant, I think Jason's feedback here basically becomes a feature request list for the Warehouse/RTD integration. Ralf may have assumed I already knew about that, but I didn't - Nathaniel's description of the link only made it sound remotely related rather than directly on-topic, and I hadn't personally encountered it through any other channels. Cheers, Nick.
On Sat, Jun 4, 2016 at 8:33 AM, Nathaniel Smith <njs@pobox.com> wrote:
How do you propose to implement and support this hypothetical doc service, given PyPI's resource constraints? Who's going to implement and maintain it? What other features are you suggesting be de-prioritized so that people can focus on this instead? Opportunity cost is a real cost.
Would it be worthwhile to write up a PEP specifying some kind of documentation API? Having something well-specified would allow a motivated non-core-Warehouse dev to implement the details and (assuming it's as uncomplicated as I imagine) just create a PR. I assume it wouldn't really need much in the way of maintenance. But it would also give the RTD folks (and others?) the ability to implement their own tools for generating/hosting the docs. -W
On 4 June 2016 at 14:54, Wayne Werner <waynejwerner@gmail.com> wrote:
On Sat, Jun 4, 2016 at 8:33 AM, Nathaniel Smith <njs@pobox.com> wrote:
How do you propose to implement and support this hypothetical doc service, given PyPI's resource constraints? Who's going to implement and maintain it? What other features are you suggesting be de-prioritized so that people can focus on this instead? Opportunity cost is a real cost.
Would it be worthwhile to write up a PEP specifying some kind of documentation API?
Having something well-specified would allow a motivated non-core-Warehouse dev to implement the details and (assuming it's as uncomplicated as I imagine) just create a PR. I assume it wouldn't really need much in the way of maintenance. But it would also give the RTD folks (and others?) the ability to implement their own tools for generating/hosting the docs.
Possibly it would be useful to write a PEP, I don't know. But even that effort needs to come from someone willing to invest the time into the work. Maybe Jason is interested in doing this, I don't know. Ultimately, I don't think there's any benefit in debating how a motivated individual should take this forward - better to leave the decisions to whoever that may be. The fundamental point is that nobody currently working on the packaging infrastructure (which mostly means "Donald"...) has sufficient time to pick this up, but that doesn't mean that someone else couldn't - just don't expect any huge amount of assistance from the existing team. Paul
participants (9)
-
Donald Stufft -
Jason R. Coombs -
Nathaniel Smith -
Nick Coghlan -
Paul Moore -
Ralf Gommers -
tritium-list＠sdamon.com -
Wayne Werner -
Wes Turner