how to make sphinx.ext.todo render in a docstring with sphinx.ext.napoleon

[raybellwaves]

Hi,

I just build the todo extension (https://github.com/raybellwaves/myfavdocs/blob/main/make_files.sh#L114-L258) but is isn't rendering as expected when I add it to a docstring (https://raybellwaves.github.io/myfavdocs/generated/myfavdocs.pd_get_random_ingredients.html). Do I need to adjust the extension?

I saw something similar in the cudf project (https://docs.rapids.ai/api/cudf/stable/user_guide/api_docs/api/cudf.dataframe.transpose/#cudf.DataFrame.transpose https://github.com/rapidsai/cudf/blob/branch-24.06/docs/cudf/source/_ext/PandasCompat.py) as was curious if they had something different that makes this kind of extension work in a docstring

EDIT:

may be related to #1837

[AA-Turner]

Hi Ray,

Are you able to provide a self-contained reproducer? Ideally a single conf.py file, index.rst, and a sample module for autodoc.

A

[raybellwaves]

Looks ok in the default config so could be related to my config above

[raybellwaves]

Just making some notes as I investigate why it may not be working for my config.

I just tested with pydata-sphinx-theme and it still works as expected.

[raybellwaves]

I see it now using sphinx.ext.napoleon and having a doc string like below. It wants to add the .. todo:: as another section in Returns

"""
Return a list of random ingredients as strings.

Parameters
----------
kind : list[str]
    Optional “kind” of ingredients.

Returns
-------
The ingredients list: list[str]

.. todo:: This is in the docstring
"""

The site is hosted here https://raybellwaves.github.io/sphinxexttesting/, the code is here https://github.com/raybellwaves/sphinxexttesting and here's a screenshot:

[picnixz]

Ok I managed to make it work:

1. You need to include todo_include_todos = True (but you probably had it already).
2. You need two new lines before the .. todo directive, namely:

"""
Return a list of random ingredients as strings.

Parameters
----------
kind : list[str]
    Optional “kind” of ingredients.

Returns
-------
The ingredients list: list[str]


.. todo:: ???
"""

By the way, thanks to you I was able to find a totally unrelated bug which, when you put 4 "?", it doesn't work!