diff --git a/CHANGELOG.rst b/CHANGELOG.rst index f62c53e..24b281e 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -15,8 +15,11 @@ Features * `#140 `: (Python) Added the ``autoapi-inheritance-diagram`` directive to create inheritance diagrams without importing modules. - Enable the ``autoapi_include_inheritance_diagrams`` option to + Enable the ``show-inheritance-diagram`` AutoAPI option to turn the diagrams on in generated documentation. +* `#183 `: (Python) + Added the ``show-inheritance`` AutoAPI option to be able to enable or disable + the display of a list of base classes in generated documentation about a class. Bug Fixes ^^^^^^^^^ diff --git a/autoapi/extension.py b/autoapi/extension.py index fe6f2cd..61c392f 100644 --- a/autoapi/extension.py +++ b/autoapi/extension.py @@ -30,7 +30,13 @@ from .toctree import add_domain_to_toctree LOGGER = sphinx.util.logging.getLogger(__name__) -_DEFAULT_OPTIONS = ["members", "undoc-members", "private-members", "special-members"] +_DEFAULT_OPTIONS = [ + "members", + "undoc-members", + "private-members", + "show-inheritance", + "special-members", +] _VIEWCODE_CACHE = {} """Caches a module's parse results for use in viewcode. @@ -261,7 +267,6 @@ def setup(app): app.add_config_value("autoapi_keep_files", False, "html") app.add_config_value("autoapi_add_toctree_entry", True, "html") app.add_config_value("autoapi_template_dir", None, "html") - app.add_config_value("autoapi_include_inheritance_graphs", False, "html") app.add_config_value("autoapi_include_summaries", False, "html") app.add_config_value("autoapi_python_use_implicit_namespaces", False, "html") app.add_config_value("autoapi_python_class_content", "class", "html") diff --git a/autoapi/mappers/base.py b/autoapi/mappers/base.py index 999703f..056fa06 100644 --- a/autoapi/mappers/base.py +++ b/autoapi/mappers/base.py @@ -86,11 +86,14 @@ class PythonMapperBase(object): def rendered(self): """Shortcut to render an object in templates.""" return self.render( - include_inheritance_graphs=self.app.config.autoapi_include_inheritance_graphs, include_private_inheritance=( "private-members" in self.app.config.autoapi_options ), include_summaries=self.app.config.autoapi_include_summaries, + show_inheritance=("show-inheritance" in self.app.config.autoapi_options), + show_inheritance_diagram=( + "show-inheritance-diagram" in self.app.config.autoapi_options + ), ) def get_context_data(self): @@ -297,11 +300,16 @@ class SphinxMapperBase(object): stringify_func=(lambda x: x[0]), ): rst = obj.render( - include_inheritance_graphs=self.app.config.autoapi_include_inheritance_graphs, include_private_inheritance=( "private-members" in self.app.config.autoapi_options ), include_summaries=self.app.config.autoapi_include_summaries, + show_inheritance=( + "show-inheritance" in self.app.config.autoapi_options + ), + show_inheritance_diagram=( + "show-inheritance-diagram" in self.app.config.autoapi_options + ), ) if not rst: continue diff --git a/autoapi/templates/python/class.rst b/autoapi/templates/python/class.rst index 513157b..2797224 100644 --- a/autoapi/templates/python/class.rst +++ b/autoapi/templates/python/class.rst @@ -3,10 +3,12 @@ {% if obj.bases %} + {% if show_inheritance %} Bases: {% for base in obj.bases %}:class:`{{ base }}`{% if not loop.last %}, {% endif %}{% endfor %} + {% endif %} - {% if include_inheritance_graphs and obj.bases != ["object"] %} + {% if show_inheritance_diagram and obj.bases != ["object"] %} .. autoapi-inheritance-diagram:: {{ obj.obj["full_name"] }} :parts: 1 {% if include_private_inheritance %}:private-bases:{% endif %} diff --git a/docs/reference/config.rst b/docs/reference/config.rst index 56580c2..9df1862 100644 --- a/docs/reference/config.rst +++ b/docs/reference/config.rst @@ -68,20 +68,26 @@ Customisation Options .. confval:: autoapi_options - Default: ``['members', 'undoc-members', 'private-members', 'special-members']`` + Default: ``['members', 'undoc-members', 'private-members', 'show-inheritance', 'special-members']`` - Options for display of the documentation. + Options for display of the generated documentation. * ``members``: Display children of an object * ``undoc-members``: Display objects that have no docstring * ``private-members``: Display private objects (eg. ``_foo`` in Python) * ``special-members``: Display special objects (eg. ``__foo__`` in Python) + * ``show-inheritance``: Display a list of base classes below the class signature. + * ``show-inheritance-diagram``: Display an inheritance diagram in + generated class documentation. + It makes use of the :mod:`sphinx.ext.inheritance_diagram` extension, + and requires `Graphviz `_ to be installed. + .. confval:: autoapi_ignore Default: Varies By Language - A list of patterns to ignore when finding files + A list of patterns to ignore when finding files. The defaults by language are: ========== ============================================ @@ -113,15 +119,6 @@ Customisation Options and you will need to include the generated documentation in a TOC tree entry yourself. -.. confval:: autoapi_include_inheritance_graphs - - Defalut: ``False`` - - Whether to include inheritance diagrams in generated class documentation. - This is a shortcut for needing to edit the templates yourself. - It makes use of the :mod:`sphinx.ext.inheritance_diagram` extension, - and requires `Graphviz `_ to be installed. - .. confval:: autoapi_include_summaries Default: ``False`` diff --git a/tests/python/pyexample/example/example.py b/tests/python/pyexample/example/example.py index 56365b1..cd6b81f 100644 --- a/tests/python/pyexample/example/example.py +++ b/tests/python/pyexample/example/example.py @@ -102,3 +102,7 @@ def decorator_okay(func): return func(*args, **kwargs) return wrapper + + +class Bar(Foo): + pass diff --git a/tests/python/test_pyintegration.py b/tests/python/test_pyintegration.py index c8ec2c5..17a2b12 100644 --- a/tests/python/test_pyintegration.py +++ b/tests/python/test_pyintegration.py @@ -91,7 +91,6 @@ class TestSimpleModule(object): assert "Meta" in index_file def test_napoleon_integration_not_loaded(self, builder): - example_path = "_build/text/autoapi/example/index.txt" with io.open(example_path, encoding="utf8") as example_handle: example_file = example_handle.read() @@ -101,6 +100,13 @@ class TestSimpleModule(object): assert "Returns" in example_file + def test_show_inheritance(self, builder): + example_path = "_build/text/autoapi/example/index.txt" + with io.open(example_path, encoding="utf8") as example_handle: + example_file = example_handle.read() + + assert "Bases:" in example_file + @pytest.mark.skipif( sys.version_info < (3,), reason="Ellipsis is invalid method contents in Python 2" @@ -344,7 +350,18 @@ def test_hiding_private_members(builder): assert "public_method" in private_file -def test_skiping_members(builder): +def test_hiding_inheritance(builder): + confoverrides = {"autoapi_options": ["members", "undoc-members", "special-members"]} + builder("pyexample", confoverrides=confoverrides) + + example_path = "_build/text/autoapi/example/index.txt" + with io.open(example_path, encoding="utf8") as example_handle: + example_file = example_handle.read() + + assert "Bases:" not in example_file + + +def test_skipping_members(builder): builder("pyskipexample") example_path = "_build/text/autoapi/example/index.txt"