IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Respect member-order="bysource" even when no analyzer is present

Browse Source 
This takes advantage of the fact that in Python 3.6 and up, the __dict__ attribute of classes and modules is insertion-ordered, which is usually a good approximation of "source order".

Notably, this means that `..automodule:: some_c_extension_module` will document members in the order they were added to the module dict, which is likely what the user wants.
This commit is contained in:
Eric Wieser 2020-05-16 12:25:42 +01:00
parent 74351b2d43
commit ebd48b9081
1 changed files with 23 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
sphinx/ext/autodoc/__init__.py
View File

@ -521,12 +521,12 @@ class Documenter:
else: else:
logger.warning(__('missing attribute %s in object %s') % logger.warning(__('missing attribute %s in object %s') %
(name, self.fullname), type='autodoc') (name, self.fullname), type='autodoc')
return False, sorted(selected) return False, selected
elif self.options.inherited_members: elif self.options.inherited_members:
return False, sorted((m.name, m.value) for m in members.values()) return False, [(m.name, m.value) for m in members.values()]
else: else:
return False, sorted((m.name, m.value) for m in members.values() return False, [(m.name, m.value) for m in members.values()
if m.directly_defined) if m.directly_defined]
def filter_members(self, members: List[Tuple[str, Any]], want_all: bool def filter_members(self, members: List[Tuple[str, Any]], want_all: bool
) -> List[Tuple[str, Any, bool]]: ) -> List[Tuple[str, Any, bool]]:
@ -699,10 +699,10 @@ class Documenter:
member_order = self.options.member_order or \ member_order = self.options.member_order or \
self.env.config.autodoc_member_order self.env.config.autodoc_member_order
if member_order == 'groupwise': if member_order == 'groupwise':
# sort by group; relies on stable sort to keep items in the # sort by group; alphabetically within groups
# same group sorted alphabetically memberdocumenters.sort(key=lambda e: (e[0].member_order, e[0].name))
memberdocumenters.sort(key=lambda e: e[0].member_order) elif member_order == 'bysource':
elif member_order == 'bysource' and self.analyzer: if self.analyzer:
# sort by source order, by virtue of the module analyzer # sort by source order, by virtue of the module analyzer
tagorder = self.analyzer.tagorder tagorder = self.analyzer.tagorder
@ -710,6 +710,15 @@ class Documenter:
fullname = entry[0].name.split('::')[1] fullname = entry[0].name.split('::')[1]
return tagorder.get(fullname, len(tagorder)) return tagorder.get(fullname, len(tagorder))
memberdocumenters.sort(key=keyfunc) memberdocumenters.sort(key=keyfunc)
else:
# Assume that member discovery order matches source order.
# This is a reasonable assumption in Python 3.6 and up, where
# module.__dict__ is insertion-ordered.
pass
elif member_order == 'alphabetical':
memberdocumenters.sort(key=lambda e: e[0].name)
else:
raise ValueError("Illegal member order {}".format(member_order))
for documenter, isattr in memberdocumenters: for documenter, isattr in memberdocumenters:
documenter.generate( documenter.generate(