How does one avoid this weird rendering of parameters?

[Vinay Sajip]

If I have additional paragraphs in my parameter descriptions, I get odd
rendering. The source is:

.. function:: some_func(param1, param2)

   Do something.

   :param param1: This renders ``somewhat`` oddly, with a dangling -- :-(
                  Assuming there is some stuff following:

                  * A
                  * B
                  * C

   :param param2: This renders in a paragraph.

and it renders as (using the Alabaster theme):

Can someone help explain how to avoid this? If I look at the nodes Sphinx
creates, I see this:

<paragraph: <literal_strong...><#text: ' – '><paragraph...><bullet_l ...>
  <literal_strong: <#text: 'param1'>>
    <#text: 'param1'>
  <#text: ' – '>
  <paragraph: <#text: 'This renders '><literal...><#text: ' oddly, wit ...>
    <#text: 'This renders '>
    <literal: <#text: 'somewhat'>>
      <#text: 'somewhat'>
    <#text: ' oddly, with a dangling – :-(\nAssuming there is some stuff follo ...'>
  <bullet_list: <list_item...><list_item...><list_item...>>
    <list_item: <paragraph...>>
      <paragraph: <#text: 'A'>>
        <#text: 'A'>
    <list_item: <paragraph...>>
      <paragraph: <#text: 'B'>>
        <#text: 'B'>
    <list_item: <paragraph...>>
      <paragraph: <#text: 'C'>>
        <#text: 'C'>
<paragraph: <literal_strong...><#text: ' – '><#text: 'This renders i ...>
  <literal_strong: <#text: 'param2'>>
    <#text: 'param2'>
  <#text: ' – '>
  <#text: 'This renders in a paragraph.'>

So in the case of param2, it's all nicely in a paragraph, but in the case of param1, a new paragraph is started immediately after the parameter name and the -- separator, leading to the observed rendering.

Is there some setting or configuration that avoids this IMO sub-optimal situation?

Regards,

Vinay Sajip

[Komiya Takeshi]

Hi,

Thank you for reporting. It's difficult situation to Sphinx. It seems
no way to avoid such output.
I'd like to try to this problem. Could you file an issue please?

Thanks,
Takeshi KOMIYA

2019年12月11日(水) 18:17 'Vinay Sajip' via sphinx-users
<sphinx...@googlegroups.com>:

>
> If I have additional paragraphs in my parameter descriptions, I get odd
> rendering. The source is:
>
> .. function:: some_func(param1, param2)
>
> Do something.
>
> :param param1: This renders ``somewhat`` oddly, with a dangling -- :-(
> Assuming there is some stuff following:
>
> * A
> * B
> * C
>
> :param param2: This renders in a paragraph.
>
> and it renders as (using the Alabaster theme):
>
>

> --
> You received this message because you are subscribed to the Google Groups "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/36a88062-c8ae-47b4-a803-e85575d8058b%40googlegroups.com.