You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Is your feature request related to a problem? Please describe.
In jaraco/path#197, the user reports the unexpected default mode of a path argument renders as 511 instead of 0o777 as it appears in the source code, potentially confusing users and guiding them away from the best practice (to use octal literals for the mode).
Describe the solution you'd like
Ideally, the autodoc feature could parse the syntax tree and determine which literals are defined using non-decimal types and reflect that syntax in the documentation.
Short of that, it would be nice if there was a feature that allowed autodoc to selectively override the signature for affected functions/methods, such as a way to say "mode=511" should be rendered as "mode=0o777" at different scopes.
Describe alternatives you've considered
One option would be to render the docs once, then make the amendments, then periodically refresh the auto-generated docs to the code to keep it approximately in sync, merging with the amendments. Such an approach is probably more toil than it's worth.
I've also looked at the docs for automethod and autofunction, but I couldn't find any options that seem appropriate for overriding the rendering of the signature.
The text was updated successfully, but these errors were encountered:
Is your feature request related to a problem? Please describe.
In jaraco/path#197, the user reports the unexpected default
mode
of a path argument renders as 511 instead of 0o777 as it appears in the source code, potentially confusing users and guiding them away from the best practice (to use octal literals for the mode).Describe the solution you'd like
Ideally, the autodoc feature could parse the syntax tree and determine which literals are defined using non-decimal types and reflect that syntax in the documentation.
Short of that, it would be nice if there was a feature that allowed autodoc to selectively override the signature for affected functions/methods, such as a way to say "mode=511" should be rendered as "mode=0o777" at different scopes.
Describe alternatives you've considered
One option would be to render the docs once, then make the amendments, then periodically refresh the auto-generated docs to the code to keep it approximately in sync, merging with the amendments. Such an approach is probably more toil than it's worth.
I've also looked at the docs for
automethod
andautofunction
, but I couldn't find any options that seem appropriate for overriding the rendering of the signature.The text was updated successfully, but these errors were encountered: