[Twisted-Python] INCOMPATIBLE CHANGE: twisted.python.dist renamed to twisted.python._setup

Adi Roiban adi at roiban.ro
Mon Aug 8 03:54:26 MDT 2016


On 8 August 2016 at 07:53, Craig Rodrigues <rodrigc at crodrigues.org> wrote:

> On Sun, Aug 7, 2016 at 11:01 PM, Glyph Lefkowitz <glyph at twistedmatrix.com>
> wrote:
>
>>
>> This is also addressing a real problem.  One of the *major* issues with
>> Twisted is *documentation noise*.  Developers trying to use Twisted to
>> build things frequently complain about this: they look for an API to do
>> XYZ, and they search the reference documentation, which produces dozens of
>> confusing, irrelevant hits.  There are multiple issues that interact here
>> (see, for example, <https://github.com/twisted/pydoctor/issues/49> which
>> is a big part of the problem) but one significant one is that our
>> apparently-public API surface is just too big.  Removing things like this,
>> which are really _totally_ useless to anyone, is useful in and of itself
>> and also amplifies the benefit of any other work on docs and tooling to
>> properly segregate public and private API documentation.
>>
>>
>
> Making dist.py private seems to fall under the category of "code
> cleanliness", and doesn't
> seem to solve any specific pressing issue that I see.  Reducing
> documentation noise is a good goal,
> but if dist.py was left the way it is, things would probably be OK with
> Twisted, and I think people
> could figure things out in Twisted with respect to the documentation.
>
> Since you mention pydoctor, I will mention two issues, that I feel are
> more important to the project
> that moving around dist.py:
>
>
>    - pydoctor produces false errors, specifically in h2 code:
>    https://buildbot.twistedmatrix.com/builders/documentation/builds/1291/
>    steps/api-documentation/logs/pydoctor%20errors
>    <https://buildbot.twistedmatrix.com/builders/documentation/builds/1291/steps/api-documentation/logs/pydoctor%20errors>
>    - pydoctor doesn't work on Python 3: https://github.com/twisted/
>    pydoctor/issues/96
>
> I have already proposed a solution for the pydoctor h2 issue
https://github.com/twisted/pydoctor/pull/126
... waiting for a review :)

-- 
Adi Roiban
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20160808/ce9dc1cf/attachment-0002.html>


More information about the Twisted-Python mailing list