bullet list rendered "opened up"

[jfbu]

Subject: why is some list at top of CHANGES rendered with paragraphs ?

Problem

http://www.sphinx-doc.org/en/master/changes.html#deprecated
renders "opened up". I don't understand why from reST source, it does not look
different from similar mark-up elsewhere.

Error logs / results

<h3>Deprecated<a class="headerlink" href="#deprecated" title="Permalink to this headline">¶</a></h3>
<ul>
<li><p class="first"><code class="docutils literal"><span class="pre">sphinx.util.compat.Directive</span></code> class is now deprecated. Please use instead
<code class="docutils literal"><span class="pre">docutils.parsers.rsr.Directive</span></code></p>
</li>

Expected results

list items do not use <p> tags

Environment info

• Sphinx version: master branch

Apologies if I am just ignorant of some reStructuredText spec.

[tk0miya]

Until docutils-0.13, its HTML writer removes <p> tag from list items if it contains only one paragraph.
And the HTML writer of Sphinx extends docutils'. In addition, readthedocs.org uses old docutils by default.

On the other hand, since docutils-0.13, CSS is used for the list compaction.

see html_compact_lists option (sphinx) and compact-lists option (docutils)
http://www.sphinx-doc.org/en/stable/config.html#confval-html_compact_lists
http://docutils.sourceforge.net/docs/user/config.html#compact-lists

[jfbu]

Thanks for info, I have reduced to MWE:

No p
----

* A
* B
* C

No p
----

* D
* E
 
  - Ea
 
* F

With p 
------

* G
* Hpre

  - Ha

  Hpost
* K

The pseudoxml output shows each list item always is <paragraph> but the html output

<h2>No p<a class="headerlink" href="#no-p" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li>A</li>
<li>B</li>
<li>C</li>
</ul>
</div>
<div class="section" id="id1">
<h2>No p<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li>D</li>
<li>E<ul>
<li>Ea</li>
</ul>
</li>
<li>F</li>
</ul>
</div>
<div class="section" id="with-p">
<h2>With p<a class="headerlink" href="#with-p" title="Permalink to this headline">¶</a></h2>
<ul>
<li><p class="first">G</p>
</li>
<li><p class="first">Hpre</p>
<ul class="simple">
<li>Ha</li>
</ul>
<p>Hpost</p>
</li>
<li><p class="first">K</p>
</li>
</ul>

With html_compact_lists = False all items have <p> tag, but with html_compact_lists = True (default), these circumstances lead to some <p> tags.

docutils 0.13.1, python 3.5.2, tested with classic and alabaster themes.

The result is discumcerting and seems to contradict the description of html_compact_lists config setting. Is this an HTML Builder issue, or my misunderstanding ?

[jfbu]

ah http://docutils.sourceforge.net/docs/user/config.html#compact-lists does indeed make me think it is simply my misunderstanding. Well in that case, DocUtils behaviour under --compact-lists option is very counter-intuitive.

[jfbu]

The description in Sphinx docs of html_compact_lists

if true, list items containing only a single paragraph will not be rendered with a <p> element. This is standard docutils behavior. Default: True.

is hard to understand. In the example above, pseudoxml gives

                <list_item>
                    <paragraph>
                        E
                    <bullet_list bullet="-">
                        <list_item>
                            <paragraph>
                                Ea

and this counts as only one paragraph for the compact lists option of Docutils. But I see one paragraph + a sublist. This makes behaviour in the end very surprising.

[jfbu]

Before closing let me add for demonstration an illustrative example

Deeply nested (simple)
----------------------

* a

  - aa

    * aaa
    * aab
    * aac

  - ab

    * aba
    * abb
    * abc

* b

  - ba

    * baa
    * bab
    * bac

  - bb

    * bba
    * bbb

      - bbba
      - bbbb

    * bbc

* c

  - ca

    * caa
    * cab
    * cac

  - cb

    * cba
    * cbb
    * cbc

Deeply nested (not simple)
--------------------------

* a

  - aa

    * aaa
    * aab
    * aac

  - ab

    * aba
    * abb
    * abc

* b

  - ba

    * baa
    * bab
    * bac

  - bb

    * bba
    * bbb

      - bbba
      - bbbb

      BBB
    * bbc

* c

  - ca

    * caa
    * cab
    * cac

  - cb

    * cba
    * cbb
    * cbc

A single change, deeply nested, has on effet on top level items, under html_compact_lists = True default, in accordance with DocUtils default behaviour.

It is hard to understand humanly the logic which leads to a, b, bb and c items ending up with <p> elements.

<h2>Deeply nested (not simple)<a class="headerlink" href="#deeply-nested-not-simple" title="Permalink to this headline">¶</a></h2>
<ul>
<li><p class="first">a</p>
<ul class="simple">
<li>aa<ul>
<li>aaa</li>
<li>aab</li>
<li>aac</li>
</ul>
</li>
<li>ab<ul>
<li>aba</li>
<li>abb</li>
<li>abc</li>
</ul>
</li>
</ul>
</li>
<li><p class="first">b</p>
<ul>
<li><p class="first">ba</p>
<ul class="simple">
<li>baa</li>
<li>bab</li>
<li>bac</li>
</ul>
</li>
<li><p class="first">bb</p>
<ul>
<li><p class="first">bba</p>
</li>
<li><p class="first">bbb</p>
<ul class="simple">
<li>bbba</li>
<li>bbbb</li>
</ul>
<p>BBB</p>
</li>
<li><p class="first">bbc</p>
</li>
</ul>
</li>
</ul>
</li>
<li><p class="first">c</p>
<ul class="simple">
<li>ca<ul>
<li>caa</li>
<li>cab</li>
<li>cac</li>
</ul>
</li>
<li>cb<ul>
<li>cba</li>
<li>cbb</li>
<li>cbc</li>
</ul>
</li>
</ul>
</li>
</ul>

[jfbu]

closed via docs made more precise at 4119439