pydoctor should hide all private names by default about pydoctor

[mwhudson]

(by mwhudson)
I agree. In general, the stuff that gets documented from @fields is not handled the same way as other things, and it should be.

[hawkowl]

Is this done to some reasonable satisfaction? @glyph

[glyph]

In the public website documentation, yeah, but in Dash (i.e.: without JavaScript) you still see private methods by default. They're also grouped according to their presence in the hierarchy, rather than private-ness, so you see private methods before you see other kinds of public methods. So I think there's still more to do here.

[hawkowl]

@glyph that seems like a Dash problem to me -- or maybe something we can fix in doc2dash (cc @hynek ). Is there such a thing as 'hidden' in dash, do you know?

[hynek]

I guess @Kapeli would be the right person to ask…

[Kapeli]

There's no such thing as hidden in Dash. However as far as I understand from @glyph's comment this is a JavaScript issue? I can definitely enable JavaScript for the Twisted docset if that's the case.

Can you give me an example of a page that contains private methods that should be hidden? This page looks the same in Dash as online: http://twistedmatrix.com/documents/current/api/twisted.internet.endpoints.TCP4ClientEndpoint.html.

[hawkowl]

@Kapeli here's one: http://twistedmatrix.com/documents/current/api/twisted.internet.endpoints.HostnameEndpoint.html

[hawkowl]

(also there's module-level stuff, e.g. http://twistedmatrix.com/documents/current/api/twisted.internet.endpoints.html )

[Kapeli]

I can't make stuff in Dash hide/unhide, so I'm thinking of doing this:

1. Only public stuff gets added to the Dash docset search index. This means you won't be able to search for any of the private stuff
2. I enable JavaScript support so you'll be able to toggle public/private as you can in your browser, but the private stuff won't appear in Dash's table of contents at the bottom left, only public will

Would that be ok?

[glyph]

@Kapeli That would definitely be an improvement. Maybe these should be command-line options in doc2dash so that maintainers could have a separate, self-generated twisted-private docset?

[Kapeli]

@hynek Could you add a command line option that would make doc2dash ignore private stuff?

[hynek]

I add command line options all the time. I’d need to know what exactly it would have to do to answer that. :)

[Kapeli]

The HTML looks like this:

<tr class="instancevariable private">
    <td>Instance Variable</td>
    <td><a href="twisted.internet.endpoints.HostnameEndpoint.html#_getaddrinfo" data-type="Instance Variable" class="code">_getaddrinfo</a></td>
    <td>A hook used for testing name resolution.</td>
</tr>

So I think in https://github.com/hynek/doc2dash/blob/master/src/doc2dash/parsers/pydoctor.py#L65 you should ignore tags for which their parent parent element contains the class "private".

Sorry for not making a pull request, but my Python knowledge is a bit non-existent.

[hynek]

The best way forward is to open an issue on doc2dash explaining briefly what the problem is and what the solution should be.

[mthuurne]

I think this issue has been resolved in pydoctor. If not, feel free to re-open, but please include an example of where the pydoctor output isn't as desired.

[glyph]

✨