Duplicated field description when using Pydantic 2.7's use_attribute_docstrings setting

[Galarzaa90]

Pydantic 2.7 added a new attribute to ModelConfig that allows fields to get its description from the docstring (See pydantic/pydantic#6563)

However, this results in a duplicate description shown in Sphinx:

Version Info:

Python 3.11
Pydantic 2.7.0
autodoc_pydantic 2.1.0
Sphinx 7.2.6 (7.3.1 is not working)

Examples

class Character(BaseModel):

    level: int = 2
    """The character's level."""

    model_config = ConfigDict(
        populate_by_name=True,
        alias_generator=to_camel,
        use_attribute_docstrings=True,
    )

[mansenfranzen]

@Galarzaa90 Thanks for reporting this issue! Nice to see pydantic using the doc strings automatically as the field description.

As a quick workaround to solve your current duplication, you can configure the docstring-policy to use the field description only.

However, for future releases, it makes sense to automatically switch the docstring policy to field description in case use_attribute_docstrings is enabled for a given model. Anything else wouldn't make much sense because the doc string should always equal the field description unless an explicit field description is provided that overwrites the doc string. What is your opinion?

[Galarzaa90]

Yeah, I upgraded as soon as I saw that feature!

Yes, I think it should be automatic, when the model uses use_attribute_docstrings , it should only use the docstring. I do not see any case where it would need to be different 🤔, since internally Field(description="") is getting replaced by the docstring.

both is defintely a useful case for when you want to have additional details in the docstring that you don't want or need to leak into specifications (e.g. OpenAPI if using FastAPI).

[mansenfranzen]

I had to rethink the way we intended the future documentation behavior in case use_attribute_docstrings is enabled. Actually, the pydantic model configuration should not overrule the docstring-policy by any means. This would in fact break existing behavior in case someone uses docstring-policy=both with a model that has fields that may contain only field descriptions or only doc strings or both at the same time. I don't want to introduce a breaking behavior. Instead, I want to ensure that no duplication takes place, as in your case.

Hence, I added a check for duplicated content provided by the field's description and the field's doc string. If they are identical, it is shown only once.

Before merging the related PR, it would be great if you could test the changed behavior. To do so, please install the current dev release in your doc-building-environment via pip install git+https://github.com/mansenfranzen/autodoc_pydantic.git@v2.2.0-a.1 and rebuild your docs.

[mansenfranzen]

@all-contributors please add @Galarzaa90 for bug

[allcontributors]

@mansenfranzen

I've put up a pull request to add @Galarzaa90! 🎉

[Galarzaa90]

@mansenfranzen I confirm this works, I removed autodoc_pydantic_field_doc_policy in order to use the default, and rebuilt with the git version and it is working fine now!

[mansenfranzen]

Thx for testing!