Skip to content

Commit 7f9757d

Browse files
committed
feat: Auto-summary of members
1 parent 0f2c25c commit 7f9757d

File tree

8 files changed

+144
-15
lines changed

8 files changed

+144
-15
lines changed

src/mkdocstrings_handlers/python/rendering.py

Lines changed: 58 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,17 @@
88
import string
99
import sys
1010
import warnings
11-
from functools import lru_cache, partial
11+
from functools import lru_cache
1212
from pathlib import Path
1313
from re import Match, Pattern
14-
from typing import TYPE_CHECKING, Any, Callable
14+
from typing import TYPE_CHECKING, Any, Callable, ClassVar
1515

1616
from griffe import (
1717
Alias,
18+
DocstringAttribute,
19+
DocstringClass,
20+
DocstringFunction,
21+
DocstringModule,
1822
DocstringSectionAttributes,
1923
DocstringSectionClasses,
2024
DocstringSectionFunctions,
@@ -481,9 +485,9 @@ def do_get_template(env: Environment, obj: str | Object) -> str | Template:
481485
@pass_context
482486
def do_as_attributes_section(
483487
context: Context, # noqa: ARG001
484-
attributes: Sequence[Attribute], # noqa: ARG001
488+
attributes: Sequence[Attribute],
485489
*,
486-
check_public: bool = True, # noqa: ARG001
490+
check_public: bool = True,
487491
) -> DocstringSectionAttributes:
488492
"""Build an attributes section from a list of attributes.
489493
@@ -494,15 +498,26 @@ def do_as_attributes_section(
494498
Returns:
495499
An attributes docstring section.
496500
"""
497-
return DocstringSectionAttributes([])
501+
return DocstringSectionAttributes(
502+
[
503+
DocstringAttribute(
504+
name=attribute.name,
505+
description=attribute.docstring.value.split("\n", 1)[0] if attribute.docstring else "",
506+
annotation=attribute.annotation,
507+
value=attribute.value, # type: ignore[arg-type]
508+
)
509+
for attribute in attributes
510+
if not check_public or attribute.is_public
511+
],
512+
)
498513

499514

500515
@pass_context
501516
def do_as_functions_section(
502-
context: Context, # noqa: ARG001
503-
functions: Sequence[Function], # noqa: ARG001
517+
context: Context,
518+
functions: Sequence[Function],
504519
*,
505-
check_public: bool = True, # noqa: ARG001
520+
check_public: bool = True,
506521
) -> DocstringSectionFunctions:
507522
"""Build a functions section from a list of functions.
508523
@@ -513,15 +528,25 @@ def do_as_functions_section(
513528
Returns:
514529
A functions docstring section.
515530
"""
516-
return DocstringSectionFunctions([])
531+
keep_init_method = not context.parent["config"]["merge_init_into_class"]
532+
return DocstringSectionFunctions(
533+
[
534+
DocstringFunction(
535+
name=function.name,
536+
description=function.docstring.value.split("\n", 1)[0] if function.docstring else "",
537+
)
538+
for function in functions
539+
if (not check_public or function.is_public) and (function.name != "__init__" or keep_init_method)
540+
],
541+
)
517542

518543

519544
@pass_context
520545
def do_as_classes_section(
521546
context: Context, # noqa: ARG001
522-
classes: Sequence[Class], # noqa: ARG001
547+
classes: Sequence[Class],
523548
*,
524-
check_public: bool = True, # noqa: ARG001
549+
check_public: bool = True,
525550
) -> DocstringSectionClasses:
526551
"""Build a classes section from a list of classes.
527552
@@ -532,15 +557,24 @@ def do_as_classes_section(
532557
Returns:
533558
A classes docstring section.
534559
"""
535-
return DocstringSectionClasses([])
560+
return DocstringSectionClasses(
561+
[
562+
DocstringClass(
563+
name=cls.name,
564+
description=cls.docstring.value.split("\n", 1)[0] if cls.docstring else "",
565+
)
566+
for cls in classes
567+
if not check_public or cls.is_public
568+
],
569+
)
536570

537571

538572
@pass_context
539573
def do_as_modules_section(
540574
context: Context, # noqa: ARG001
541-
modules: Sequence[Module], # noqa: ARG001
575+
modules: Sequence[Module],
542576
*,
543-
check_public: bool = True, # noqa: ARG001
577+
check_public: bool = True,
544578
) -> DocstringSectionModules:
545579
"""Build a modules section from a list of modules.
546580
@@ -551,7 +585,16 @@ def do_as_modules_section(
551585
Returns:
552586
A modules docstring section.
553587
"""
554-
return DocstringSectionModules([])
588+
return DocstringSectionModules(
589+
[
590+
DocstringModule(
591+
name=module.name,
592+
description=module.docstring.value.split("\n", 1)[0] if module.docstring else "",
593+
)
594+
for module in modules
595+
if not check_public or module
596+
],
597+
)
555598

556599

557600
class AutorefsHook(AutorefsHookInterface):

src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,14 @@ Context:
142142
{% endif %}
143143
{% endblock docstring %}
144144

145+
{% block summary scoped %}
146+
{#- Summary block.
147+
148+
This block renders auto-summaries for classes, methods, and attributes.
149+
-#}
150+
{% include "summary"|get_template with context %}
151+
{% endblock summary %}
152+
145153
{% block source scoped %}
146154
{#- Source block.
147155

src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,14 @@ Context:
9797
{% endwith %}
9898
{% endblock docstring %}
9999

100+
{% block summary scoped %}
101+
{#- Summary block.
102+
103+
This block renders auto-summaries for classes, methods, and attributes.
104+
-#}
105+
{% include "summary"|get_template with context %}
106+
{% endblock summary %}
107+
100108
{% block children scoped %}
101109
{#- Children block.
102110

src/mkdocstrings_handlers/python/templates/material/_base/summary.html.jinja

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,21 @@
66
This block can be used to log debug messages, deprecation messages, warnings, etc.
77
-#}
88
{% endblock logs %}
9+
10+
{% with members_list = config.members if root_members else None %}
11+
{% if config.summary.modules %}
12+
{% include "summary/modules"|get_template with context %}
13+
{% endif %}
14+
15+
{% if config.summary.classes %}
16+
{% include "summary/classes"|get_template with context %}
17+
{% endif %}
18+
19+
{% if config.summary.functions %}
20+
{% include "summary/functions"|get_template with context %}
21+
{% endif %}
22+
23+
{% if config.summary.attributes %}
24+
{% include "summary/attributes"|get_template with context %}
25+
{% endif %}
26+
{% endwith %}

src/mkdocstrings_handlers/python/templates/material/_base/summary/attributes.html.jinja

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,16 @@
66
This block can be used to log debug messages, deprecation messages, warnings, etc.
77
-#}
88
{% endblock logs %}
9+
10+
{% with section = obj.attributes
11+
|filter_objects(
12+
filters=config.filters,
13+
members_list=members_list,
14+
inherited_members=config.inherited_members,
15+
keep_no_docstrings=config.show_if_no_docstring,
16+
)
17+
|order_members(config.members_order, members_list)
18+
|as_attributes_section(check_public=not members_list)
19+
%}
20+
{% if section %}{% include "docstring/attributes"|get_template with context %}{% endif %}
21+
{% endwith %}

src/mkdocstrings_handlers/python/templates/material/_base/summary/classes.html.jinja

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,16 @@
66
This block can be used to log debug messages, deprecation messages, warnings, etc.
77
-#}
88
{% endblock logs %}
9+
10+
{% with section = obj.classes
11+
|filter_objects(
12+
filters=config.filters,
13+
members_list=members_list,
14+
inherited_members=config.inherited_members,
15+
keep_no_docstrings=config.show_if_no_docstring,
16+
)
17+
|order_members(config.members_order, members_list)
18+
|as_classes_section(check_public=not members_list)
19+
%}
20+
{% if section %}{% include "docstring/classes"|get_template with context %}{% endif %}
21+
{% endwith %}

src/mkdocstrings_handlers/python/templates/material/_base/summary/functions.html.jinja

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,16 @@
66
This block can be used to log debug messages, deprecation messages, warnings, etc.
77
-#}
88
{% endblock logs %}
9+
10+
{% with section = obj.functions
11+
|filter_objects(
12+
filters=config.filters,
13+
members_list=members_list,
14+
inherited_members=config.inherited_members,
15+
keep_no_docstrings=config.show_if_no_docstring,
16+
)
17+
|order_members(config.members_order, members_list)
18+
|as_functions_section(check_public=not members_list)
19+
%}
20+
{% if section %}{% include "docstring/functions"|get_template with context %}{% endif %}
21+
{% endwith %}

src/mkdocstrings_handlers/python/templates/material/_base/summary/modules.html.jinja

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,16 @@
66
This block can be used to log debug messages, deprecation messages, warnings, etc.
77
-#}
88
{% endblock logs %}
9+
10+
{% with section = obj.modules
11+
|filter_objects(
12+
filters=config.filters,
13+
members_list=members_list,
14+
inherited_members=config.inherited_members,
15+
keep_no_docstrings=config.show_if_no_docstring,
16+
)
17+
|order_members(config.members_order.alphabetical, members_list)
18+
|as_modules_section(check_public=not members_list)
19+
%}
20+
{% if section %}{% include "docstring/modules"|get_template with context %}{% endif %}
21+
{% endwith %}

0 commit comments

Comments
 (0)