Skip to content
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 for non-decimal literals (oct, hex, bin) in autodoc signatures #8636

Closed
jaraco opened this issue Dec 31, 2020 · 1 comment
Closed
Labels

Comments

@jaraco
Copy link

jaraco commented Dec 31, 2020

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.

@jaraco jaraco added the type:enhancement enhance or introduce a new feature label Dec 31, 2020
@tk0miya
Copy link
Member

tk0miya commented Jan 1, 2021

Thank you for posting. Same as #759.

@tk0miya tk0miya closed this as completed Jan 1, 2021
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jul 16, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Projects
None yet
Development

No branches or pull requests

2 participants