private stuff should be private-er

[Glyph Lefkowitz]

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).

[Michael Hudson-Doyle (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?).

[Glyph Lefkowitz (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.)