On 8 August 2016 at 07:53, Craig Rodrigues <rodr...@crodrigues.org> wrote:
> On Sun, Aug 7, 2016 at 11:01 PM, Glyph Lefkowitz <gl...@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
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
