-
-
Notifications
You must be signed in to change notification settings - Fork 2.1k
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
Fixing poor docstring formatting for @callback #2728
base: dev
Are you sure you want to change the base?
Conversation
…sues. Replaced it with a heading for the section and paragraph separated portions for each function parameter.
…hin the parameter list.
…cters at the end of each keyword subsection.
Thank you for this PR, @woefulpines . We appreciate the time you put into this. |
Thanks @woefulpines! The main thing I'm concerned about here is how it works with the dash docs reference pages: https://dash.plotly.com/reference#dash.callback is auto-generated from this docstring. Frankly I'd prefer to move away from reStructuredText entirely, in favor of something more human-centered, perhaps looking more like component docstrings (which are themselves autogenerated). FYI @LiamConnors |
Out of curiosity, how do you generate your documentation? Is there some resource that talks about it? |
Also I realized now that dash/dash.py has an example of feature lists working in the vscode doc popup window so I can try that for the time being and have some changes that may be more inline with your standards. |
Unfortunately our docs repo is private, just because we use our enterprise packages in it. But we’ve been discussing some ways to potentially open it up, which would make this kind of thing a lot easier! |
…ility while avoiding linter blank line errors.
I added feature lists back in. I wasn't able to use blank lines to format the docstring, I hope newlines wont give the document generator any trouble. Looking at dash/dash.py. The comment for the dash class is allowed to use blank lines and it also has type annotations in the docstring for each parameter. So if those were things you would like in the callback docstring, I can add them in. Thank for your patience with this. I really appreciate it. |
@LiamConnors can you please either merge or close? thank you - @gvwilson |
It seems like some reStructuredText elements don't render well in vscodes docstring preview window #2670. I replaced feature lists with elements that were supported according to this example in pandas contributing guidelines. In terms of content, nothing is added or changed, just formatted it differently.