left sidebar has unknown icon

[XavieLee]

Hi team, I got this issue when migrate theme from sphinx-material to sphinx-immaterial. May I know how to fix it? sphinx-immaterial version: 0.13.5 Thanks!

Here is my config.

...
html_theme_options = {
    'repo_url': 'https://github.com/trinodb/trino',
    'repo_name': 'Trino',
    'icon': {
        'repo': 'fontawesome/brands/github-alt'
    },
    'version_json': '../versions.json',
    'palette': [
        {
            'media': '(prefers-color-scheme)',
            'scheme': 'default',
            'toggle': {
                'icon': 'material/brightness-auto',
                'name': 'Switch to light mode',
            }
        },
        {
            'media': '(prefers-color-scheme: light)',
            'scheme': 'default',
            'toggle': {
                'icon': 'material/weather-sunny',
                'name': 'Switch to dark mode',
            }
        },
        {
            'media': '(prefers-color-scheme: dark)',
            'scheme': 'slate',
            'toggle': {
                'icon': 'material/weather-night',
                'name': 'Switch to system preference',
            }
        },
    ],
    'font': {
        'text': 'Roboto',
        'code': 'Roboto Mono'
    },
    'features': [
        'navigation.expand',
        'navigation.top',
        'navigation.path',
        'search.highlight',
        'search.share',
        'toc.follow',
        'toc.integrate'
    ]
}
...

[2bndy5]

It's because you enabled toc.integrate feature. And, the "Date and time" section is somehow getting treated as an API entity. It can be customized, see our docs.

[XavieLee]

Thanks! I have fixed that by updating config file.

object_description_options = [
    ("py:.*", dict(toc_icon_class=None))
]

[jbms]

There is still some underlying bug, though --- it shouldn't be necessary to remove those icons.

Can you share a minimal reproduction?

[2bndy5]

Without more detail or a sample that can reproduce the issue, I'm closing this as not planned.

Also, it looks like the trino project is now leaning toward not switching to this theme for various reasons. Unfortunately for them, the sphinx-material theme they're pinned to isn't being actively maintained anymore.

[XavieLee]

Hi team, sorry for the late reply. I was on a business trip last week. I will share a sample to help figure out the issue.

[XavieLee]

hi @jbms @2bndy5 , u can access this repo to reproduce the issue. https://github.com/XavieLee/trino-docs-test

1. execute command to build

rm -rf target/html target/doctrees
sphinx-build -q -j auto -b html -W --keep-going -d target/doctrees src/main/sphinx target/html 

2. access xxx/xxx/trino-docs/target/html/functions.html

3. then u can see the issue

[2bndy5]

It would help to have a requirements.txt file for the docs' dependencies. The conf.py lists a few extensions that I'm not familiar with.

[2bndy5]

I managed to reduce the sample to just a few pages.

trino-445-sample.zip

It looks like the bug only happens after enabling myst-parser's colon-fence extension. This tells me that using the manual domain definitions like

:::{data} current_date
Returns the current date as of the start of the query.
:::


:::{function} date(x) -> date
This is an alias for `CAST(x AS date)`.
:::

which seem to instigate treating the page title as an API entity (specifically as a python parameter).

---

I also suspect that using myst-parser's toctree directive may be causing #448 because my smaller sample also reproduces that issue.

[2bndy5]

FYI, this is not proper a type annotation:

:::{function} round(x) -> [same as input]
Returns `x` rounded to the nearest integer.
:::

Since this is using the python domain, I would recommend using a generic type (see py docs and related sphinx docs).

:::{type} T
A generic type used for functions that take various data types.
:::

<!-- ... -->

:::{function} round(x: T) -> T
Returns `x` rounded to the nearest integer.
:::

[2bndy5]

This issues seems to occur when using :no-index: option of duplicate function definitions.

:::{function} timezone(timestamp(p) with time zone) -> varchar 

Returns the timezone identifier from `timestamp(p) with time zone`. The format
of the returned identifier is identical to the [format used in the input
timestamp](#):

```sql
SELECT timezone(TIMESTAMP '2024-01-01 12:00:00 Asia/Tokyo'); -- Asia/Tokyo
SELECT timezone(TIMESTAMP '2024-01-01 12:00:00 +01:00'); -- +01:00
SELECT timezone(TIMESTAMP '2024-02-29 12:00:00 UTC'); -- UTC
```
:::

:::{function} timezone(time(p) with time zone) -> varchar
:no-index:
Returns the timezone identifier from a `time(p) with time zone`. The format
of the returned identifier is identical to the [format used in the input
time](#):

```sql
SELECT timezone(TIME '12:00:00+09:00'); -- +09:00
```
:::

If I remove the second function definition, then the unexpected icon in the global ToC is not present.

Unfortunately, it looks like myst-parser does not support documenting overloaded functions. Myst-parser might also fail to recognize the second signature since it is not a valid python signature. Instead, you could use the eval-rst directive to document overloaded functions with multiple signatures.

[!note] Myst-parser doesn't seem to recognize the eval-rst directive when using a colon-fenced block (:::\n...\n:::).

```{eval-rst}
.. function:: timezone(timestamp(p) with time zone) -> varchar
              timezone(time(p) with time zone) -> varchar

    Returns the timezone identifier from ``timestamp(p) with time zone`` or 
    ``time(p) with time zone``.
    The format of the returned identifier is identical to the `format used in the input
    timestamp or time <#>`_:

    .. code-block:: sql

        SELECT timezone(TIMESTAMP '2024-01-01 12:00:00 Asia/Tokyo'); -- Asia/Tokyo
        SELECT timezone(TIMESTAMP '2024-01-01 12:00:00 +01:00'); -- +01:00
        SELECT timezone(TIMESTAMP '2024-02-29 12:00:00 UTC'); -- UTC
 
    .. code-block:: sql

        SELECT timezone(TIME '12:00:00+09:00'); -- +09:00
```

will render as expected: