Codegen for list of features truncates description

[steveluscher]

Consider the list of features page:

https://tsfresh.readthedocs.io/en/latest/text/list_of_features.html

Whose source is here:

https://github.com/blue-yonder/tsfresh/blob/main/docs/text/list_of_features.rst

The problem is that, if a feature's docstring contains line breaks, the full description doesn't get included into the HTML.

Example, this docstring results in the description ‘This function calculates the value of’ rather than the entire thing:

https://github.com/blue-yonder/tsfresh/blob/860c4e1702ef5e397b8291578f7b1557052db459/tsfresh/feature_extraction/feature_calculators.py#L1497-L1526

[steveluscher]

This might turn out to be a bug report for whoever supplies your docgen. Unless, of course, there's something you can do to make the docstring more amenable to the docgen.

[nils-braun]

That is a reasonable bug you are raising here.

Only including the first sentence into the table was actually a "design" decision as the full docstring would probably make this table a lot longer. It is possible to still get the full docstring by clicking on the function name. However, that is not a very good UX, so your bug report is quite valuable :-)

I see two possibilities:

• Add a sentence on this page to explain that this is only a short description and more information is in the detail pages. But then we should definitely make sure that this first sentence is actually reasonable (not like in the example you are giving).
• Or we include the full docstring onto this page, but we have some very long docstrings (like this) that we would need to shorten then.

What do you think?

[steveluscher]

We should do something like this!

This function calculates the value of<span class="expander">&hellip; <a href="#">See more</a></span> <span class="expanderContinuation">{REST OF THE DESCRIPTION}</span>

…clicking the link would remove expander and reveal expanderContinuation.

[nils-braun]

That would be cool, but would definitely need a custom sphinx-plugin (or even a custom documentation generator for this), as using only the first line is hard-coded into the autosummary extension we are using (at least as far as I have understood the code).

I am not sure I (personally) have the capacity to do so currently, but if you have an easy solution or you would like to support here, I am very happy!

[MaxBenChrist]

related to #832

I think google also recommends in their python style guide to have a short description of each python fuunction in the first line of the docstring, then later a block with more detailed descriptions. That paradigm sounds reasonable to me and is only in the interest of the toctree parser (which just parses the first sentence of the docstring of each feature calculator. I added some part on the "how to write a feature calculator" tutorial to follow that design