-
-
Notifications
You must be signed in to change notification settings - Fork 1
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
feature: Add additional "merge" strategy / mode and allow specifying it during init #2
Comments
Thanks for opening the issue here again! So, I'm not convinced by But then... how do we merge? In the previous issue/PR, you also had a delimiter setting IIRC, and had set it to Could you elaborate your use-case regarding the different ways we can merge, and give examples of parent/child classes and the resulting merged docstrings? 🙂 |
Yes, I'll elaborate more! I thought of using You're right, a merge delimiter should also be part of the config, with a default of perhaps
and others like this:
Having just one So the config could look like this: - mkdocstrings:
handlers:
python:
paths: [src]
options:
extensions:
- griffe_inherited_docstrings:
inherit_docstring_strategy: "merge" (default is "if_not_present")
merge_delimiter: "\n\n" Example: merge_delimiter = "+",
|
Ooooh OK I see, thanks, that's much simpler than I thought. Then I suggest we go with this:
There are very low chances we change the default strategy IMO. And concatenating with WDYT? |
Sounds good. One last thing to perhaps clarify: Currently, for all members docstring inheritance is performed. Do you think we should allow customizablity like: Or just wait for user requests as well? |
We wait 🙂 Users come up with all kind of requests that we can't predict in advance 😄 |
Cf. mkdocstrings/python#194
Sphinx performs some merging of docstrings1, as demonstrated below.
Example:
For this example, the merged docstring for
surface_area
should be: "Return the surface area in square meters. Note: This is way faster than the calculation for general shapes!"Having this feature and being able to set it during init of
InheritDocstringsExtension
would allow to use it inmkdocs.yml
like this:Happy to contribute a solution :)
Footnotes
Compare
MetaLearner.evaluate
with e.g.RLearner.evaluate
. Just beforeParameters
, RLearner has an additional paragraph that stems from this docstring ↩The text was updated successfully, but these errors were encountered: