search

mansenfranzen / autodoc_pydantic

Seamlessly integrate pydantic models in your Sphinx documentation.
MIT License
155 stars 27 forks source link

Model subclasses do not show superclass fields #32

Closed matutter closed 3 years ago

matutter commented 3 years ago

I cannot find a way to show all fields of a model if it subclasses another BaseModel.

class MyBase(BaseModel):
  field_on_base: str

class MySubclass(MyBase):
  field_on_subclass: str

When generate the model's docs with autopydantic_model both field_on_base and field_on_subclass is shown in the field list however only the docstring of field_on_subclass is shown.

.. currentmodule:: tests

.. autopydantic_model:: MySubclass
mansenfranzen commented 3 years ago

@matutter Thanks for reporting the issue. I can reproduce what you've observed.

By default, sphinx autodoc does not include any member (attributes or methods) from base classes. However, it has a directive option named :inherited-members: which allows you to include all members from all super classes except from object (see docs here). Unfortunately, this will also include all members from pydantic.BaseModel (e.g. copy(), schema() etc...). Luckily, :inherited-members: takes a parameter which allows to exclude base classes. As a working example, you could use the following which should work just fine for you:

tests.py

from pydantic import BaseModel

class MyBase(BaseModel):
    field_on_base: str

class MySubclass(MyBase):
    field_on_subclass: str

index.rst

.. currentmodule:: tests

.. autopydantic_model:: MySubclass
   :inherited-members: BaseModel

Even though this might work for you already, it also reveals an incosistency in autodoc_pydantic. The fields list should be aligned with the members that get documented. In case :inherited-members: BaseModel is not used, only field_on_subclass should be documented in both the field list and the class body. Otherwise, both field_on_base and field_on_subclass have to be documented.

Therefore, I suggest that field list and also its cousin the validator list should respect :inherited-members:. Additionally, it could be sensible to add a new configuration flag to activate :inherited-members: BaseModel by default. What do you think?

mansenfranzen commented 3 years ago

@matutter The current dev release now respects inherited members. It is aligned with the default sphinx autodoc behavior. Additionally, a section in the FAQ now describes how to display fields/validators from base classes (see here).

Before merging the related PR, it would be great if you could test the bug fix on your site to confirm that my test case did indeed capture the incorrect behavior which you've encountered. To do so, please install the current dev release in your doc-building-environment via pip install git+git://github.com/mansenfranzen/autodoc_pydantic.git@v1.4.0-a.2 and rebuild your docs.

matutter commented 3 years ago

@mansenfranzen confirmed this produced the expected output. Inherited members are included when using the :inherited-members: BaseModel. All expected members are present. Thank you!!

mansenfranzen commented 3 years ago

Closing this issue via #37

FraDV0695 commented 2 weeks ago

is it possible to set this operation inside the conf.py file? I would like to make the attributes inherited from the parent classes be shown in all the pydantic classes of the project automatically, when I generate the files using sphinx-apidoc.