On Sun, Aug 7, 2016 at 11:01 PM, Glyph Lefkowitz <glyph@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
• pydoctor doesn't work on Python 3: https://github.com/twisted/pydoctor/issues/96