Make identifiers sorting optional

[nicolaskruchten]

Would you accept a PR to make sorting optional in the documentation (new CLI arg, defaulting to current behaviour)? I rather like the order in which the functions/methods are declared in my module and I'd rather the documentation follow that order rather than a strictly alphabetical one :)

[kernc]

Certainly! What approach were you going to go about it? I think I'd prefer the flag passed to methods (e.g. Class.functions(sort=True)) from inside the template instead of passed through Module / Class constructors.

[nicolaskruchten]

That makes sense to me, thanks for the input!

[nicolaskruchten]

Unfortunately this will not be trivial, as inspect.getmembers() returns items pre-sorted :(

[kernc]

In CPython 3.6+ (Python 3.7+), traversing .__dict__ should retain definition order (?). This shouldn't be a problem since we filter "own" members anyway:

pdoc/pdoc/__init__.py

Lines 1134 to 1139 in c423762

	public_objs = [(name, inspect.unwrap(obj))
	for name, obj in inspect.getmembers(self.obj)
	# Filter only *own* members. The rest are inherited
	# in Class._fill_inheritance()
	if (name in self.obj.__dict__ and
	(_is_public(name) or name == '__init__'))]

[nicolaskruchten]

Right but the issue is that the inspect module already sorts items before returning them so the initial order is already lost by the time this code executes.

[kernc]

I thought you were intent on changing this code. 😀

We can iterate over self.obj.__dict__ as a replacement for inspect.getmembers(). 👍

[nicolaskruchten]

Ah gotcha. I wasn’t sure how deep you were OK with me going in terms of these modifications :) should I aim to remove the use of inspect altogether?

[kernc]

You just make it work.

But altogether no. inspect is actually the preferred API, so only where no other way around, like here.