Function parens not showing up in right sidebar ToC

[kattni]

Upstream ref link:

• Function names not rendering in right sidebar ToC with parens mkdocstrings/mkdocstrings#773

---

Hello!

This theme is lovely, and I greatly appreciate the extensive configuration options.

I'm running into an issue that I initially was initially assuming was mkdocstrings, but I'm starting to wonder if it's related to the theme. I have some auto-generated reference documentation, and the list of functions in the right sidebar are being listed without () following, i.e. function() is showing up as function. I have found screenshots of others' documentation, and the parens are present in screenshots I've found, however, there's never any clear information on what the associated configurations or settings are.

I have included a screenshot - everything under "Context" should be showing up followed by "()".

My current theme feature settings are as follows:

  features:
    - content.tabs.link
    - toc.follow
    - navigation.path

I may be missing some kind of configuration somewhere, however I can't find any reference to what might be causing this in the documentation.

If it turns out it is in fact related to mkdocstrings, I apologise for taking up your time. For what it's worth, in the event you are familiar with its configuration, these are the options I currently have set:

          options:
            docstring_style: sphinx
            show_source: false
            members_order: source
            annotations_path: brief
            merge_init_into_class: true
            separate_signature: true
            show_signature: true
            show_signature_annotations: false
            signature_crossrefs: true
            show_root_heading: true

I can't find anything in those docs specific to this either though, which is leading to my confusion as to which bit is responsible.

Thanks so much for your time!
Kattni

[kamilkrzyskow]

Hi @kattni,
it's my first time seeing parenthesis shortened as parens 👀 maybe it will catch on 😆

As for the issue at hand, there are headings in your Content and they're added to the ToC with a modified toc-label value to make them more readable.

First let's talk about the Content. You've enabled separate_signature, which puts the signature in a code block below the function name heading. As seen with your redraw function. In general I would recommend to keep it as-is, as enabling the signature in the heading makes it less readable. The image below shows it disabled, and here's the original. Also even though there is the content with parens in the heading, as you see, it's still not part of the ToC entry.

The rendering of the ToC is done by the templates provided by the MkDocstrings Python handler (as you're using Python code, right?).
Here's the related code, maybe it's not exactly this but close enough ✌️

It's using the function.name from the Griffe library,
https://mkdocstrings.github.io/griffe/reference/api/models/function/#griffe.Function.name
You could try to override it somehow using either template modification or monkey patching to add the () if the object is of type function. I've done sone mkdocstrings customizing inside of Nype's theme repository, so you could have a look to reference my hacking methods 😎 , but I didn't really do anything with the ToC.

But apart of adding (), the recommended approach is to enable "type hints", per the show_symbol_type_toc option in the Python handler.

[kattni]

Hello @kamilkrzyskow!

Thank you so much for your prompt and thorough response! I especially appreciate you taking the time, even though it seems to be an issue more likely related to mkdocstrings.

I think I understand how it can be changed in a theme override. I will have to do some testing to see if I can figure out how to do it.

I decided to go back through and see if I could find one of the examples I saw in my digging. This screenshot is from a 2020 article.

However, if you view the actual documentation, as it is now (this for example), there are no parens present in the sidebar ToC.

I am now wondering if it was a feature that was removed between then and now. I will reach out to the mkdocstrings folks to, if nothing else, find out if it ever really existed and if it was removed. I will follow up here if I find out anything potentially useful.

Thank you again! We are currently exploring whether a move from Sphinx to MkDocs is feasible or worth the effort, and the Material theme has certainly provided features that are lending to the switch being more viable.

Cheers!

[kamilkrzyskow]

The current version of the linked page is made using Astro, as can be seen in the HTML source
<meta name="generator" content="Astro v5.11.0">

As for the date, 2020 seems like a time before the Griffe library, as the changelog starts in 2021:
https://mkdocstrings.github.io/griffe/changelog/

So you could try to use the legacy variant of the Python handler:
https://mkdocstrings.github.io/usage/handlers/#about-the-python-handlers

Their repository from December 2020 unfortunately doesn't specify the versions of the packages.
So you'd have to do quite a bit of digging to see what versions were compatible at this point and download a compatible Python version.
I don't think that's worth your time TBH, just pointing out a crazy possibility of getting to the bottom of this😅
https://github.com/up42/up42-py/tree/0.14.0

[kattni]

Ahh! Well that may at least explain the differences I'm seeing. It's possible Griffe never rendered things like that.

I did post a question to the mkdocstrings folks. I'll keep you posted.

I do agree digging into legacy code is not worth my time. I'd rather spend that time sorting out a theme override, if it turns out that's what's necessary. 😅

Thank you again!

[kattni]

They were removed in this commit in favor of displaying the symbol types.

The solution provided here will be my plan if the project lead prefers functions to render as they are now with () afterwards. Thanks so much for the help!