[Python-ideas] Linking Doug's stdlib documentation to our main modules doc.
doug.hellmann at gmail.com
Sat Mar 19 15:54:32 CET 2011
On Mar 19, 2011, at 10:26 AM, Mike Meyer wrote:
> On Sat, 19 Mar 2011 12:48:48 +1100
> Steven D'Aprano <steve at pearwood.info> wrote:
>> But that's not my main objection. We keep the bar high for inclusion in
>> the standard library, and it shouldn't offend anyone.
> Has treating the documentation like the library been considered? That
> is, instead of linking to Doug's examples, assuming Doug consented,
> incorporate them directly into the doc, and give Doug a commit bit so
> he can maintain them. That would also solve the versioning issues, at
> least to the level of "which version is the example for." Done right,
> the examples should be automatically testable.
Some of the examples were copied into the standard library docs as part of the GHOP context a few years ago. I would prefer not to incorporate everything directly, for now, because it would complicate the licensing for publication.
I appreciate everyone's willingness to discuss Tarek's proposal and consider alternatives, but I think it is probably best to leave things as they are until there is an official policy on outbound links from the standard library docs. I agree that having a large number of links to other sites would be a maintenance burden, so I completely understand the reluctance to take that on as a project.
Drawing a parallel from the way the library code is handled, it seems best to treat PyMOTW as a separately maintained resource and let users find it separately. Now, if there was an index equivalent to PyPI for documentation resources, *that* would complete the analogy. :-)
More information about the Python-ideas