diff --git a/.changelog/_unreleased.toml b/.changelog/_unreleased.toml index a4be08ed..65aca089 100644 --- a/.changelog/_unreleased.toml +++ b/.changelog/_unreleased.toml @@ -32,3 +32,10 @@ type = "docs" description = "Fix links to docspec" author = "@rafalkrupinski" pr = "https://github.com/NiklasRosenstein/pydoc-markdown/pull/337" + +[[entries]] +id = "bdae0469-fd87-40be-aaae-7a9c08c074da" +type = "improvement" +description = "Sort within the Markdown renderer" +author = "usmfi@student.kit.edu" +pr = "https://github.com/NiklasRosenstein/pydoc-markdown/pull/342" diff --git a/src/pydoc_markdown/contrib/renderers/markdown.py b/src/pydoc_markdown/contrib/renderers/markdown.py index 2e478b08..49e6524b 100644 --- a/src/pydoc_markdown/contrib/renderers/markdown.py +++ b/src/pydoc_markdown/contrib/renderers/markdown.py @@ -195,6 +195,9 @@ class MarkdownRenderer(Renderer, SinglePageRenderer, SingleObjectRenderer): } ) + #: Sort the members of API objects by name + sort_alphabetically: bool = True + #: A plugin that implements the #SourceLinker interface to provide links to the #: source code of API objects. If this field is specified, the renderer will #: place links to the source code in the generated Markdown files. @@ -243,7 +246,12 @@ def _render_toc(self, fp: t.TextIO, level: int, obj: docspec.ApiObject): title = title.split(".")[-1] fp.write(" " * level + "* [{}](#{})\n".format(title, object_id)) level += 1 - for child in getattr(obj, "members", []): + + members = getattr(obj, "members", []) + if self.sort_alphabetically: + members = sorted(members, key=lambda m: m.name.lower()) + + for child in members: self._render_toc(fp, level, child) def _render_header(self, fp: t.TextIO, level: int, obj: docspec.ApiObject): @@ -383,7 +391,12 @@ def _render_object(self, fp: t.TextIO, level: int, obj: docspec.ApiObject): def _render_recursive(self, fp: t.TextIO, level: int, obj: docspec.ApiObject): self._render_object(fp, level, obj) level += 1 - for member in getattr(obj, "members", []): + + members = getattr(obj, "members", []) + if self.sort_alphabetically: + members = sorted(members, key=lambda m: m.name.lower()) + + for member in members: self._render_recursive(fp, level, member) def _get_title(self, obj: docspec.ApiObject) -> str: @@ -450,6 +463,10 @@ def render_single_page( if self.render_page_title: fp.write("# {}\n\n".format(page_title)) + # Sort modules alphabetically by name for consistent ordering + if self.sort_alphabetically: + modules = sorted(modules, key=lambda m: m.name.lower()) + if self.render_toc: if self.render_toc_title: if self.render_page_title: @@ -458,8 +475,8 @@ def render_single_page( else: fp.write("# {}\n\n".format(self.render_toc_title)) - for m in modules: - self._render_toc(fp, 0, m) + for m in modules: + self._render_toc(fp, 0, m) fp.write("\n") for m in modules: self._render_recursive(fp, 1, m)