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

An option to control whether the admonitions in python docstring should be collapsed #22

Closed
asakiasako opened this issue Jun 1, 2022 · 9 comments
Labels
feature New feature or request

Comments

@asakiasako
Copy link

asakiasako commented Jun 1, 2022

Is your feature request related to a problem? Please describe.
When I use admonitions in python docstring like this:

"""
Note:
    Details ...
"""

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 😂

@asakiasako asakiasako changed the title A question about admonitions An option to control whether the admonitions in docsting should be collapsed Jun 10, 2022
@asakiasako asakiasako changed the title An option to control whether the admonitions in docsting should be collapsed An option to control whether the admonitions in python docstring should be collapsed Jun 10, 2022
@pawamoy
Copy link
Member

pawamoy commented Jun 10, 2022

Thanks for the report! I was able to replicate. I went with details + summary HTML tags for admonitions, but I see now that other admonitions use divs and classes. We can either add open="" by default on details, change the admonition template to match other admonitions, or let users override it.

From this:

{{ log.debug("Rendering admonition") }}
<details class="{{ section.value.kind }}">
  <summary>{{ section.title|convert_markdown(heading_level, html_id, strip_paragraph=True) }}</summary>
  {{ section.value.contents|convert_markdown(heading_level, html_id) }}
</details>

...to this:

{{ log.debug("Rendering admonition") }}
<div class="admonition {{ section.value.kind }}">
  <p class="admonition-title">{{ section.title|convert_markdown(heading_level, html_id, strip_paragraph=True) }}</p>
  {{ section.value.contents|convert_markdown(heading_level, html_id) }}
</div>

Not sure what is the most sensible solution 😕 The div+class method might not render well with themes other than the Material one.
@facelessuser, maybe you could give us some hindsight? (is it OK if I ping you like that by the way?)

I also don't see a clean way to control it from the markup itself (from within the docstring) 😕 Open to suggestions.

@facelessuser
Copy link

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 😕.

@pawamoy
Copy link
Member

pawamoy commented Jun 10, 2022

Argh, for some reason I thought the admonition extension was part of PyMdown Extensions... I guess the similar syntax and this paragraph is the reason why. My bad. I think I'll stick with details and default to open="".

@lukaszmoroz
Copy link

lukaszmoroz commented Jul 11, 2022

+1 for making open default.

I also don't see a clean way to control it from the markup itself (from within the docstring) confused Open to suggestions.

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 Note, See also, etc.

@levzlotnik
Copy link

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?

@asakiasako
Copy link
Author

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('')

@IceBotYT
Copy link

First output the site and then run the workaround.

How would I go about this using GitHub Actions?

@inpbox
Copy link

inpbox commented Feb 17, 2023

Argh, for some reason I thought the admonition extension was part of PyMdown Extensions... I guess the similar syntax and this paragraph is the reason why. My bad. I think I'll stick with details and default to open="".

Thanks for an awesome project. I've got:

mkdocs 1.4.2
mkdocstrings 0.20.0
mkdocs-material 9.0.12

and I see the "details" in the admonitions as "collapsed" and not "open" for the final html output.

python_mkdocstrings_admonitions_collapsed

Any way to override this setting, or is it on the todo-list to be implemented?

@pawamoy pawamoy added the feature New feature or request label Mar 5, 2023
pawamoy added a commit that referenced this issue Apr 11, 2023
@pawamoy
Copy link
Member

pawamoy commented Apr 11, 2023

Fixed in 79cd153, will release soon.

@pawamoy pawamoy closed this as completed Apr 11, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feature New feature or request
Projects
None yet
Development

No branches or pull requests

7 participants