Skip to content

Commit 54a3ac3

Browse files
astrofrogastrofrog
authored
Merge pull request #197 from WilliamJamieson/autoproperty
Add option to document properties using autoproperty instead of autoattribute
2 parents f8690bc + 09aeffb commit 54a3ac3

File tree

92 files changed

+817
-12
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

92 files changed

+817
-12
lines changed

‎CHANGES.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@ Changes in sphinx-automodapi
44
0.19.0 (unreleased)
55
-------------------
66

7+
- Add ``automodsumm_properties_are_attributes`` configuration to control if
8+
class properties are treated with ``autoattribute`` or ``autoproperty``.
9+
[#197]
10+
711
0.18.0 (2024-09-13)
812
-------------------
913

‎sphinx_automodapi/automodapi.py

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,11 @@ class are included in the generated documentation. Defaults to ``False``.
104104
methods like ``__getitem__`` and ``__setitem__``. Defaults to
105105
``['__init__', '__call__']``.
106106
107+
* ``automodsumm_properties_are_attributes``
108+
Should be a bool and if ``True`` properties are treated as attributes in the
109+
documentation meaning that no property specific documentation is generated.
110+
Defaults to ``True``.
111+
107112
.. _automodule: http://sphinx-doc.org/latest/ext/autodoc.html?highlight=automodule#directive-automodule
108113
"""
109114

‎sphinx_automodapi/automodsumm.py

Lines changed: 23 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,11 @@ class members that are inherited from a base class. This value can be
7474
methods like ``__getitem__`` and ``__setitem__``. Defaults to
7575
``['__init__', '__call__']``.
7676
77+
* ``automodsumm_properties_are_attributes``
78+
Should be a bool and if ``True`` properties are treated as attributes in the
79+
documentation meaning that no property specific documentation is generated.
80+
Defaults to ``True``.
81+
7782
.. _sphinx.ext.autosummary: http://sphinx-doc.org/latest/ext/autosummary.html
7883
.. _autosummary: http://sphinx-doc.org/latest/ext/autosummary.html#directive-autosummary
7984
@@ -321,7 +326,8 @@ def process_automodsumm_generation(app):
321326
lines, sfn, app=app, builder=app.builder,
322327
base_path=app.srcdir,
323328
inherited_members=app.config.automodsumm_inherited_members,
324-
included_members=app.config.automodsumm_included_members)
329+
included_members=app.config.automodsumm_included_members,
330+
properties_are_attributes=app.config.automodsumm_properties_are_attributes)
325331

326332

327333
# _automodsummrex = re.compile(r'^(\s*)\.\. automodsumm::\s*([A-Za-z0-9_.]+)\s*'
@@ -462,7 +468,8 @@ def generate_automodsumm_docs(lines, srcfn, app=None, suffix='.rst',
462468
base_path=None, builder=None,
463469
template_dir=None,
464470
inherited_members=False,
465-
included_members=('__init__', '__call__')):
471+
included_members=('__init__', '__call__'),
472+
*, properties_are_attributes=True):
466473
"""
467474
This function is adapted from
468475
`sphinx.ext.autosummary.generate.generate_autosummmary_docs` to
@@ -595,10 +602,10 @@ def get_members_class(obj, typ, include_public=[],
595602
continue
596603
if typ is None or documenter.objtype == typ:
597604
items.append(name)
598-
elif typ == 'attribute' and documenter.objtype == 'property':
599-
# In Sphinx 2.0 and above, properties have a separate
600-
# objtype, but we treat them the same here.
601-
items.append(name)
605+
# elif typ == 'attribute' and documenter.objtype == 'property':
606+
# # In Sphinx 2.0 and above, properties have a separate
607+
# # objtype, but we treat them the same here.
608+
# items.append(name)
602609
public = [x for x in items
603610
if x in include_public or not x.startswith('_')]
604611
return public, items
@@ -629,6 +636,15 @@ def get_members_class(obj, typ, include_public=[],
629636
ns['attributes'], ns['all_attributes'] = \
630637
get_members_class(obj, 'attribute',
631638
include_base=include_base)
639+
public_properties, all_properties = \
640+
get_members_class(obj, 'property',
641+
include_base=include_base)
642+
if properties_are_attributes:
643+
ns['attributes'].extend(public_properties)
644+
ns['all_attributes'].extend(all_properties)
645+
else:
646+
ns['properties'] = public_properties
647+
ns['all_properties'] = all_properties
632648
ns['methods'].sort()
633649
ns['attributes'].sort()
634650

@@ -703,6 +719,7 @@ def setup(app):
703719
app.add_config_value('automodsumm_inherited_members', False, 'env')
704720
app.add_config_value(
705721
'automodsumm_included_members', ['__init__', '__call__'], 'env')
722+
app.add_config_value('automodsumm_properties_are_attributes', True, 'env')
706723

707724
return {'parallel_read_safe': True,
708725
'parallel_write_safe': True}

‎sphinx_automodapi/templates/autosummary_core/class.rst

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
{% endif %}
1919

2020
{% block attributes_summary %}
21-
{% if attributes %}
21+
{% if attributes or properties %}
2222

2323
.. rubric:: Attributes Summary
2424

@@ -27,6 +27,10 @@
2727
~{{ name }}.{{ item }}
2828
{%- endfor %}
2929

30+
{% for item in properties %}
31+
~{{ name }}.{{ item }}
32+
{%- endfor %}
33+
3034
{% endif %}
3135
{% endblock %}
3236

@@ -44,14 +48,18 @@
4448
{% endblock %}
4549

4650
{% block attributes_documentation %}
47-
{% if attributes %}
51+
{% if attributes or properties%}
4852

4953
.. rubric:: Attributes Documentation
5054

5155
{% for item in attributes %}
5256
.. autoattribute:: {{ item }}
5357
{%- endfor %}
5458

59+
{% for item in properties %}
60+
.. autoproperty:: {{ item }}
61+
{%- endfor %}
62+
5563
{% endif %}
5664
{% endblock %}
5765

‎sphinx_automodapi/tests/cases/abstract_classes/output/api/sphinx_automodapi.tests.example_module.abstract_classes.SequenceSubclass.rst renamed to ‎sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.abstract_classes.SequenceSubclass.rst

File renamed without changes.

‎sphinx_automodapi/tests/cases/abstract_classes/output/index.rst.automodapi renamed to ‎sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_attr/index.rst.automodapi

File renamed without changes.

‎sphinx_automodapi/tests/cases/abstract_classes/output/index.rst.automodsumm renamed to ‎sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_attr/index.rst.automodsumm

File renamed without changes.

‎sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.abstract_classes.SequenceSubclass.rst

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
SequenceSubclass
2+
================
3+
4+
.. currentmodule:: sphinx_automodapi.tests.example_module.abstract_classes
5+
6+
.. autoclass:: SequenceSubclass
7+
:show-inheritance:
8+
9+
.. rubric:: Attributes Summary
10+
11+
.. autosummary::
12+
13+
~SequenceSubclass.my_property
14+
15+
.. rubric:: Methods Summary
16+
17+
.. autosummary::
18+
19+
~SequenceSubclass.my_method
20+
21+
.. rubric:: Attributes Documentation
22+
23+
.. autoproperty:: my_property
24+
25+
.. rubric:: Methods Documentation
26+
27+
.. automethod:: my_method

‎sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_not_attr/index.rst.automodapi

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
2+
sphinx_automodapi.tests.example_module.abstract_classes Module
3+
--------------------------------------------------------------
4+
5+
.. automodule:: sphinx_automodapi.tests.example_module.abstract_classes
6+
7+
Classes
8+
^^^^^^^
9+
10+
.. automodsumm:: sphinx_automodapi.tests.example_module.abstract_classes
11+
:classes-only:
12+
:toctree: api
13+
14+
Class Inheritance Diagram
15+
^^^^^^^^^^^^^^^^^^^^^^^^^
16+
17+
.. automod-diagram:: sphinx_automodapi.tests.example_module.abstract_classes
18+
:private-bases:
19+
:parts: 1

‎sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_not_attr/index.rst.automodsumm

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.. currentmodule:: sphinx_automodapi.tests.example_module.abstract_classes
2+
3+
.. autosummary::
4+
:toctree: api
5+
6+
SequenceSubclass

‎sphinx_automodapi/tests/cases/allowed_names/output/api/sphinx_automodapi.tests.example_module.Egg.rst renamed to ‎sphinx_automodapi/tests/cases/allowed_names/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Egg.rst

File renamed without changes.

‎sphinx_automodapi/tests/cases/allowed_names/output/api/sphinx_automodapi.tests.example_module.Spam.rst renamed to ‎sphinx_automodapi/tests/cases/allowed_names/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.Spam.rst

File renamed without changes.

‎sphinx_automodapi/tests/cases/allowed_names/output/index.rst.automodapi renamed to ‎sphinx_automodapi/tests/cases/allowed_names/output_prop_is_attr/index.rst.automodapi

File renamed without changes.

‎sphinx_automodapi/tests/cases/allowed_names/output/index.rst.automodsumm renamed to ‎sphinx_automodapi/tests/cases/allowed_names/output_prop_is_attr/index.rst.automodsumm

File renamed without changes.

‎sphinx_automodapi/tests/cases/allowed_names/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Egg.rst

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
Egg
2+
===
3+
4+
.. currentmodule:: sphinx_automodapi.tests.example_module
5+
6+
.. autoclass:: Egg
7+
:show-inheritance:
8+
9+
.. rubric:: Attributes Summary
10+
11+
.. autosummary::
12+
13+
~Egg.weight
14+
15+
.. rubric:: Methods Summary
16+
17+
.. autosummary::
18+
19+
~Egg.buy
20+
~Egg.eat
21+
22+
.. rubric:: Attributes Documentation
23+
24+
.. autoproperty:: weight
25+
26+
.. rubric:: Methods Documentation
27+
28+
.. automethod:: buy
29+
.. automethod:: eat

‎sphinx_automodapi/tests/cases/mixed_toplevel/output/api/sphinx_automodapi.tests.example_module.Spam.rst renamed to ‎sphinx_automodapi/tests/cases/allowed_names/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.Spam.rst

File renamed without changes.

‎sphinx_automodapi/tests/cases/allowed_names/output_prop_is_not_attr/index.rst.automodapi

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
2+
sphinx_automodapi.tests.example_module Package
3+
----------------------------------------------
4+
5+
.. automodule:: sphinx_automodapi.tests.example_module
6+
7+
Classes
8+
^^^^^^^
9+
10+
.. automodsumm:: sphinx_automodapi.tests.example_module
11+
:classes-only:
12+
:toctree: api
13+
:allowed-package-names: sphinx_automodapi.tests.example_module.classes
14+
15+
Class Inheritance Diagram
16+
^^^^^^^^^^^^^^^^^^^^^^^^^
17+
18+
.. automod-diagram:: sphinx_automodapi.tests.example_module
19+
:private-bases:
20+
:parts: 1
21+
:allowed-package-names: sphinx_automodapi.tests.example_module.classes

‎sphinx_automodapi/tests/cases/allowed_names/output_prop_is_not_attr/index.rst.automodsumm

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. currentmodule:: sphinx_automodapi.tests.example_module
2+
3+
.. autosummary::
4+
:toctree: api
5+
6+
Egg
7+
Spam

‎sphinx_automodapi/tests/cases/attribute_class/README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
This example is to make sure that classes can have attributes and properties
2+
and they can be distiguished if ``automodsumm_properties_are_attributes = False``

‎sphinx_automodapi/tests/cases/attribute_class/input/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.. automodapi:: sphinx_automodapi.tests.example_module.attribute_class

‎sphinx_automodapi/tests/cases/attribute_class/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.attribute_class.ClassWithAttribute.rst

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
ClassWithAttribute
2+
==================
3+
4+
.. currentmodule:: sphinx_automodapi.tests.example_module.attribute_class
5+
6+
.. autoclass:: ClassWithAttribute
7+
:show-inheritance:
8+
9+
.. rubric:: Attributes Summary
10+
11+
.. autosummary::
12+
13+
~ClassWithAttribute.my_attribute
14+
~ClassWithAttribute.my_property
15+
16+
.. rubric:: Methods Summary
17+
18+
.. autosummary::
19+
20+
~ClassWithAttribute.my_method
21+
22+
.. rubric:: Attributes Documentation
23+
24+
.. autoattribute:: my_attribute
25+
.. autoattribute:: my_property
26+
27+
.. rubric:: Methods Documentation
28+
29+
.. automethod:: my_method

‎sphinx_automodapi/tests/cases/attribute_class/output_prop_is_attr/index.rst.automodapi

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
2+
sphinx_automodapi.tests.example_module.attribute_class Module
3+
-------------------------------------------------------------
4+
5+
.. automodule:: sphinx_automodapi.tests.example_module.attribute_class
6+
7+
Classes
8+
^^^^^^^
9+
10+
.. automodsumm:: sphinx_automodapi.tests.example_module.attribute_class
11+
:classes-only:
12+
:toctree: api
13+
14+
Class Inheritance Diagram
15+
^^^^^^^^^^^^^^^^^^^^^^^^^
16+
17+
.. automod-diagram:: sphinx_automodapi.tests.example_module.attribute_class
18+
:private-bases:
19+
:parts: 1

‎sphinx_automodapi/tests/cases/attribute_class/output_prop_is_attr/index.rst.automodsumm

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.. currentmodule:: sphinx_automodapi.tests.example_module.attribute_class
2+
3+
.. autosummary::
4+
:toctree: api
5+
6+
ClassWithAttribute

‎sphinx_automodapi/tests/cases/attribute_class/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.attribute_class.ClassWithAttribute.rst

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
ClassWithAttribute
2+
==================
3+
4+
.. currentmodule:: sphinx_automodapi.tests.example_module.attribute_class
5+
6+
.. autoclass:: ClassWithAttribute
7+
:show-inheritance:
8+
9+
.. rubric:: Attributes Summary
10+
11+
.. autosummary::
12+
13+
~ClassWithAttribute.my_attribute
14+
15+
~ClassWithAttribute.my_property
16+
17+
.. rubric:: Methods Summary
18+
19+
.. autosummary::
20+
21+
~ClassWithAttribute.my_method
22+
23+
.. rubric:: Attributes Documentation
24+
25+
.. autoattribute:: my_attribute
26+
27+
.. autoproperty:: my_property
28+
29+
.. rubric:: Methods Documentation
30+
31+
.. automethod:: my_method

‎sphinx_automodapi/tests/cases/attribute_class/output_prop_is_not_attr/index.rst.automodapi

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
2+
sphinx_automodapi.tests.example_module.attribute_class Module
3+
-------------------------------------------------------------
4+
5+
.. automodule:: sphinx_automodapi.tests.example_module.attribute_class
6+
7+
Classes
8+
^^^^^^^
9+
10+
.. automodsumm:: sphinx_automodapi.tests.example_module.attribute_class
11+
:classes-only:
12+
:toctree: api
13+
14+
Class Inheritance Diagram
15+
^^^^^^^^^^^^^^^^^^^^^^^^^
16+
17+
.. automod-diagram:: sphinx_automodapi.tests.example_module.attribute_class
18+
:private-bases:
19+
:parts: 1

‎sphinx_automodapi/tests/cases/attribute_class/output_prop_is_not_attr/index.rst.automodsumm

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.. currentmodule:: sphinx_automodapi.tests.example_module.attribute_class
2+
3+
.. autosummary::
4+
:toctree: api
5+
6+
ClassWithAttribute

‎sphinx_automodapi/tests/cases/classes_no_inherit/output/api/sphinx_automodapi.tests.example_module.classes.Egg.rst renamed to ‎sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst

File renamed without changes.

‎sphinx_automodapi/tests/cases/classes_no_inherit/output/index.rst.automodapi renamed to ‎sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_attr/index.rst.automodapi

File renamed without changes.

‎sphinx_automodapi/tests/cases/classes_no_inherit/output/index.rst.automodsumm renamed to ‎sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_attr/index.rst.automodsumm

File renamed without changes.

‎sphinx_automodapi/tests/cases/classes_no_inherit/output_prop_is_not_attr/api/sphinx_automodapi.tests.example_module.classes.Egg.rst

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
Egg
2+
===
3+
4+
.. currentmodule:: sphinx_automodapi.tests.example_module.classes
5+
6+
.. autoclass:: Egg
7+
:show-inheritance:
8+
9+
.. rubric:: Attributes Summary
10+
11+
.. autosummary::
12+
13+
~Egg.weight
14+
15+
.. rubric:: Methods Summary
16+
17+
.. autosummary::
18+
19+
~Egg.buy
20+
~Egg.eat
21+
22+
.. rubric:: Attributes Documentation
23+
24+
.. autoproperty:: weight
25+
26+
.. rubric:: Methods Documentation
27+
28+
.. automethod:: buy
29+
.. automethod:: eat

0 commit comments

Comments
 (0)