mansenfranzen / autodoc_pydantic

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

Miss configuration for inheritance-members in conf.py #303

Open FraDV0695 opened 2 months ago

FraDV0695 commented 2 months ago

The problem is similar to what was reported in this old issue

I am finding this sphinx extension very useful for managing the documentation of pydantic classes.

However, I am having quite a few problems generating correct documentation of classes when they inherit attributes from other parent classes (whether implemented in the same project or imported from external libraries). Through configuration management of both autodo_pydantic and autosummaary, I managed to partially obtain what I wanted: I can document all the attributes of the target class (both native and inherited), but all the methods and validators of the parent classes are also documented (especially those of the BaseModel class).

The suggestion given in the FAQ unfortunately does not help me, as I have no experience in generating templates for Sphinx. Furthermore, in my case, the manual modification that is suggested is impractical, since I automatically generate all the .rst files with sphinx-apidoc.

Instead of manually modifying the .rst files, would it not be possible to integrate this extension with the configuration parameters to handle this case, so as to be able to improve the automation of the documentation with this extension?

this are my general configuration inside the conf.py

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.autodoc',
    'm2r2',
    'sphinx.ext.githubpages',
    'sphinx.ext.autosummary',
    'sphinxcontrib.autodoc_pydantic'
]
autoclass_content = 'both'

autodoc_pydantic_config_members = False
autodoc_pydantic_model_show_config_summary = False # Show model config summary within the class doc string
autodoc_pydantic_model_show_validator_members = False
# autodoc_pydantic_model_show_field_summary = False
autodoc_pydantic_model_show_json = False # Show the schema json representation of a pydantic model within in the class doc string as a collapsable code block.
autodoc_pydantic_field_list_validators = False
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False

autosummary_generate = True
autodoc_default_options = {
    'members': True,
    'undoc_members': True,
    'show-inheritance': True,
    'inherited-members': True,
    #'imported-members': True
}
mansenfranzen commented 2 months ago

Hi @FraDV0695,

thanks for raising your issue here!

If I understand you correctly, you would like to have a global configuration property that removes all inherited members from documented models by default, right?