New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Support/respect autodoc's autodoc_preserve_defaults
and autodoc_typehints_format
settings
#95
Comments
@Yoshanuikabundi Thanks for opening an issue here again 😄. I agree, this would be a nice enhancement. To be more concretely, this would apply to pydantic field signatures specifically, right? I will take a look into it and how to support it for newer sphinx versions. |
😁 This would apply to field signatures for sure, but possibly also other signatures. It already works for methods, but having it for validators and configs and whatever else in addition to fields would be maximally consistent 😃 |
@Yoshanuikabundi I finally manage to take a closer look at your proposal. While I'm still totally convinced that shortening type hints and preserving defaults do improve documentation, I have doubts where and how to implement it. ExampleMore concretely, lets consider the following example: example.py from pydantic import BaseModel
import io
class PydanticModel(BaseModel):
"""Doc String.
"""
field: io.StringIO = io.StringIO()
"""Summy dummy docs"""
class Config:
arbitrary_types_allowed = True
def some_class_func(self, i2: io.StringIO = io.StringIO()) -> io.StringIO:
"""Some docs"""
pass
class PlainPython:
"""Doc String.
"""
field: io.StringIO = io.StringIO()
"""Summy dummy docs"""
def some_class_func(self, i2: io.StringIO = io.StringIO()) -> io.StringIO:
"""Some docs"""
pass
def dummy_func(i: io.StringIO, i2: io.StringIO = io.StringIO()) -> io.StringIO:
"""Some docs"""
pass conf.py extensions = ["sphinxcontrib.autodoc_pydantic"]
autodoc_typehints_format = "short"
autodoc_preserve_defaults = True ResultsGenerating docs for
ConclusionWithout taking a look at the actual sphinx implementation, it is obvious that plain sphinx autodoc does actually not respect In general, Moreover, I see this as an inconsistent behaviour in sphinx autodoc that Anyway, you could argue that What is your take on this? |
Thanks for looking into this! Sorry, I didn't even consider the possibility that this might be Thanks! |
Hi ! Maybe this comment can help ? sphinx-doc/sphinx#10290 (comment) |
In the last few releases, autodoc has added two settings to
conf.py
that are very useful:autodoc_preserve_defaults
: Preserves default argument values as they are in code, rather than evaluating themautodoc_typehints_format
: Suppresses the module names of type hintsBy turning each of these on, a field signature could be transformed from something like this:
to
Which is much less intimidating and easier to read.
It would be amazing if autodoc_pydantic could support these options in pydantic models etc.
The text was updated successfully, but these errors were encountered: