Comments (7)
Let's go with autodoc_pydantic_field_show_optional
for all fields which are not obviously optional (e.g. field: int = 1
). Thanks for sharing your thoughts on those naming conventions - really appreciate it.
from autodoc_pydantic.
Thanks for pointing this out! Technically, it is correct to have the PydanticUndefined
default value because the default value is not known until object instantiation of the corresponding class that inherits from pydantic BaseModel
. The documentation is generated from the class and not from instances of it.
However, for documentation purposes, a rather non technical label/marker is more appropriate, I agree. You've proposed the [has default]
marker. That's a good starting point. Perhaps the less the better - let's just hide the default value completely for PydanticUndefined
default values because the opposite case is explicitly marked via [required]
.
I suggest we add a new configuration property named autodoc_pydantic_field_hide_undefined_default_value
. What's your opinion on that?
from autodoc_pydantic.
Perhaps the less the better - let's just hide the default value completely for
PydanticUndefined
default values because the opposite case is explicitly marked via[required]
.
Normally I am a huge fan of keeping things short but this is imho one of the times where I think explicit is better than implicit.
If I don't know any of the internals and read the docs for the first time it's immediately clear that
- values that have a default are optional
- values that are required and don't have a default have the
[Required]
tag
If there is no [Required]
tag and no default things are ambiguous and it's not clear if the field can be omitted.
Thus I really thing there should be some kind of marker that indicates that I don't have to specify a value for this field.
How about the opposite of [Required]
: [Optional]
?
The config switch could than be named autodoc_pydantic_field_show_default_factory_as_optional
.
from autodoc_pydantic.
You have convinced me - let's be more explicit.
In support of your point, the optional/required tag might be even necessary even if the type already contains Optional[int]
because:
field_a: Optional[int]
is indeed optional- while
field_b: Optional[int] = ...
is required
I added an example section outlining all these possibilities here. Taking a closer look at this example, it becomes evident that all = PydanticUndefined
could be converted into [Optional]
.
So, taking this into account, what about autodoc_pydantic_field_mark_undefined_as_optional
?
from autodoc_pydantic.
I think show
instead of mark
would be more consistent with the already existing configuration options.
How about autodoc_pydantic_field_show_pydantic_undefined_as_optional
?
autodoc_pydantic_field_show_undefined_as_optional
is fine, too.
On the other hand the required marker uses autodoc_pydantic_field_show_required
so maybe autodoc_pydantic_field_show_optional
would be the most consistent one?
Thank you for your help!
from autodoc_pydantic.
@spacemanspiff2007 This feature request should be accomplished via #117
- Documentation on the new configuration property
autodoc_pydantic_field_show_optional
: click - Updated documentation on the example for required/optional fields: click
By the way, I took the chance to modify how the default value is fetched from pydantic fields. This results in properly showing the default value None
for all plain optional fields such as field: Optional[int]
.
Before merging the related PR, it would be great if you could test the behavior on your site. To do so, please install the current dev release in your doc-building-environment via pip install git+https://github.com/mansenfranzen/[email protected]
and rebuild your docs.
from autodoc_pydantic.
Looks good! Thank you for the quick implementation!
from autodoc_pydantic.
Related Issues (20)
- Cannot generate documentation when having class with arbitrary types HOT 1
- Cannot use `inherited-members` directive with autosummary HOT 5
- Generate output with nonvalidation methods HOT 4
- ForwardRef.__init__() got an unexpected keyword argument 'is_class' HOT 3
- Render field examples HOT 2
- Type aliases don't propagate for nested pydantic models with inherited members.
- Allow `autodoc_pydantic_field_signature_prefix` to be empty HOT 5
- Does `autodoc-pydantic` support the `pydantic.v1` compatibility layer? HOT 2
- `model_post_init` from `BaseModel` appears in the rendered documentation HOT 5
- [Feature Request] Print json schema as (collapsible) table HOT 2
- model_computed_fields is shown in rendered output HOT 3
- Consider dropping support for sphinx version 4.X HOT 3
- Model inherited from two parents does not seem to show inherited members HOT 1
- Dependency Dashboard
- Test PR Agent Behavior HOT 1
- erdantic v1.0 coming soon HOT 5
- Duplicated field description when using Pydantic 2.7's use_attribute_docstrings setting HOT 7
- Bug: Failed import on sphinx 7.3 HOT 6
- Autodoc Pydantic not working with Sphinx 7.3 HOT 12
- Exception during build: `AttributeError: 'tuple' object has no attribute 'rebuild'` HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from autodoc_pydantic.