-
-
Notifications
You must be signed in to change notification settings - Fork 40
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
An option to control whether the admonitions in python docstring should be collapsed #22
Comments
Thanks for the report! I was able to replicate. I went with From this:
...to this:
Not sure what is the most sensible solution 😕 The div+class method might not render well with themes other than the Material one. I also don't see a clean way to control it from the markup itself (from within the docstring) 😕 Open to suggestions. |
I'm a bit confused about what is exactly being asked. Admonitions don't collapse details are collapsable. I haven't used mkdocstrings, so I don't know what it is doing or what is being asked of me 😕. |
Argh, for some reason I thought the |
+1 for making
Maybe allow to control it through options: either the default behavior, or each kind separately, or both: <!-- templates/material/_base/docstring/admonition.html -->
{% set admonition_config = (config.admonitions | default({}))[section.value.kind] | default({}) %}
{% set open = admonition_config.open | default(config.admonitions_default_open) %}
<details class="{{ section.value.kind }}" {% if open %}open{% endif %}>
<summary>{{ section.title|convert_markdown(heading_level, html_id, strip_paragraph=True) }}</summary>
{{ section.value.contents|convert_markdown(heading_level, html_id) }}
</details> And then: # mkdocs.yml
plugins:
- mkdocstrings:
handlers:
python:
options:
admonitions_default_open: false
admonitions:
note: { open: true } Possibly also adding control to whether the admonitions should be collapsible at all. I think this is sensible enough as usually there will be a finite number of admonitions used in docstrings, like |
Hey mkdocstrings team, thank you so much for making this extension! It's really cool and helped me in my work significantly! I ran into the same small issue while writing documentation for my project, is there any plan to support configurable admonitions like in this discussion? Or is there a temporary workaround I can apply in my project by including some JS/CSS? |
For now, I write a workaround in python which modifies the outputed html files directly. First output the site and then run the workaround. You can see if it can help you. def fix_admonition_collapse():
print('=======================\nfix_admonition_collapse\n=======================')
api_names = ['abc', 'models']
PATTERN = re.compile(
r'<details class="(.*?">\n'
r'\s*)<summary>(?!Source code in)(.*?)<\/summary>(\n'
r'(.*\n)*?'
r')<\/details>'
)
for n in api_names:
filepath = f'./site/api/{n}/index.html'
with open(filepath, 'r') as fp:
s = fp.read()
c = len(PATTERN.findall(s))
new_s = PATTERN.sub(r'<div class="admonition \1<p class="admonition-title">\2</p>\3</div>', s)
with open(filepath, 'w') as fp:
fp.write(new_s)
print(f'{c} modifications in {filepath}')
print('') |
How would I go about this using GitHub Actions? |
Thanks for an awesome project. I've got:
and I see the "details" in the admonitions as "collapsed" and not "open" for the final html output. Any way to override this setting, or is it on the todo-list to be implemented? |
Fixed in 79cd153, will release soon. |
Is your feature request related to a problem? Please describe.
When I use admonitions in python docstring like this:
I noticed that an collapsed admonitions is rendered in the browser now.
I can use
!!! note
to make a uncollapsed admonition, but this will make the docstring strange for human reading.Describe the solution you'd like
The information contained in 'Note' or 'Tips' or other admonitions are usually important information, and we don't want our users to miss them, so I think at least we have a choise to choose whether it should be collapsed.
Platform: Windows 10
mkdocstrings == 0.19.0
mkdocstrings-python == 0.7.0
griffe == 0.20.0
I don't know if I described the situation clearly 😂
The text was updated successfully, but these errors were encountered: