pydoctor should hide all private names by default

[mwhudson]

https://bugs.launchpad.net/pydoctor/+bug/209077 was a step forward, but it was not consistently applied.

For example, the "instance variables" section on http://twistedmatrix.com/documents/10.1.0/api/twisted.internet.endpoints.TCP4ClientEndpoint.html still doesn't render the private instance variables differently.

While displaying private names is useful to maintainers, the main public documentation really shouldn't show the private names at all, and should instead have a link that says "show all private names".

---

Imported from Launchpad using lp2gh.

• date created: 2010-07-20T22:19:35Z
• owner: glyph
• the launchpad url was https://bugs.launchpad.net/bugs/607987

[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]

✨