private stuff should be private-er

[mwhudson]

There is some visible indication that _-prefixed names are private when looking at the index, but when looking at the documentation for individual methods or functions, the text is on the same blue background.

Better would be a consistent style that always showed private stuff, in any context, as grey-on-grey so it's clear.

Also, the grey-on-grey doesn't ever have a textual explanation. There should be some text saying "This method is for maintainers only" and a link to a page that explains what it means to call a private method.

Finally, private methods should all be hidden by default, and shown via a "show private methods and bases" button (assuming the browser has JavaScript).

---

Imported from Launchpad using lp2gh.

• date created: 2012-05-09T19:50:53Z
• owner: glyph
• the launchpad url was https://bugs.launchpad.net/bugs/997295

[mwhudson]

(by mwhudson)
Thank you for reporting three bugs at once :-)

The first should be easy (simple CSS tweak, he says confidently)

Doesn't the third subsume the second? I think if grey stuff appears when you click "show maintainer only content", that's a lesson that will be learnt pretty quickly.

The third part should be easy. I don't know if I want to write any raw js though, so I probably get to decide which js library to use first...

People who use browsers without js are clearly not using the internet anyway, so I don't really care about them (maybe blind people get a pass?).

[mwhudson]

(by glyph)
On May 9, 2012, at 8:20 PM, Michael Hudson-Doyle wrote:

Thank you for reporting three bugs at once :-)

I tried hard not to make it 4 :). By all means feel free to split this up and subscribe me to all of them.

The first should be easy (simple CSS tweak, he says confidently)

How hard could it be?

Doesn't the third subsume the second? I think if grey stuff appears
when you click "show maintainer only content", that's a lesson that will
be learnt pretty quickly.

More specificity is probably good though. Keep in mind that public/private conventions are not terribly well-defined in the Python community (c.f. sys._getframe(), a public API if ever I saw one), and even less well-understood by Python newbies, but the PyDoctor-using community seems a bit more rigorous about it.

The third part should be easy. I don't know if I want to write any raw
js though, so I probably get to decide which js library to use first...

Can't you just use document.styleSheets to twiddle a single CSS rule to turn off display:none? I know that JS is inconsistent and stuff, and libraries are great, but really, this ought to be a one-liner...

People who use browsers without js are clearly not using the internet
anyway, so I don't really care about them (maybe blind people get a
pass?).

Yeah I don't think I care much either. But, it might be nice if it didn't break for them, since the sort of people who try to browse without JS are exactly the sort of nerds who might want to read the twisted documentation. (I don't mind telling them that they need a user stylesheet though.)

[tristanlatr]

I think this issue can be closed.
There is a JS button to switch from public / private view.

Some users might want to display everything tho, so maybe an option to make everything public make sens.

[mthuurne]

The original ticket asked for both a public/private toggle and for a way to see what is private when everything is visible. We have the former, but not the latter. Do we want the latter as well?

For users that want to see everything, maybe we can add an argument to the URL's query? That would allow linking to the "show private definitions" version.

[adiroiban]

I think that the current implementation is good enough.
The initial report is from 2015.

If this is still an issue this can be reopened or create a new issue.

[mthuurne]

We actually do have a way to see what is private when "show private API" is enabled: the background for the private names is gray. I think I'd prefer something orthogonal to our usual colors that indicate methods, attributes etc., but it satisfies the request from this issue.

The query argument was added in #351.

I'll close this now. If there are more wishes, please create a new ticket for each of them.