Fix multi-paragraph issue entries

[bitprophet]

Example:

* :bug:`122` Yup.
* :bug:`123` Foo the bars and stuff. blah blah.

  Also more stuff related to 123 cuz wow, such bugfix, very commits, so complex.
* :feature:`120` Some other asshole

Current released version actually ignores the 2nd paragraph for bug 123 due to implementation details.

I have a fix already in place (changes implementation to be more flexible, pull issue out while replacing it, then re-insert instead of recreating structure from whole cloth) but remaining:

• [ ] Test suite is now too simplistic due to use of simple lists to fake iterable docutils node objects; needs updating.
• [ ] Docutils seems to do dumb ass shit with non complex lists, e.g. http://docutils.sourceforge.net/sandbox/html4strict/data/simple-lists.html
  • The end result for us is that any lists containing 'non simple' list items (such as...the multi paragraph ones that this is about) preserve the paragraphs, which then add trailing whitespace and such, and all others lose the paragraphs they originally had.
  • All other lists look "normal" with regular whitespace between the list-items.
  • So now "random" release sublists look funny and have much more internal spacing than all the others. Looks bad.
  • Action items:
  • see if we can fix with styling, though it'd have to be something all users add to their specific stylesheets :( (or we insert inline styling, which is kinda gross and not cascadable.)
  • or figure out how to work around this modification, such that we either undo the paragraph removal (making everything consistent, if whitespace heavy) or replace multiple paragraphs with <br> tags or something. There's an option for this in docutils, but eg the sphinx-build -A option doesn't seem to do the trick.
    • Latter not great because the general point is to allow users to put arbitrary ReST inside these line items and have them preserved.

[bitprophet]

Hrmph, yea I even have some multi "block" items in the Paramiko changelog where the 2nd item isn't even a paragraph but is eg a nested list. So making assumptions about that (aka the "replace with BR tags" idea) is just not gonna fly.

Similarly, attempting to tweak styling as I was thinking - remove the bottom-margin on p.first, then add top-margin on :not(p.first) or however one uses :not - also doesn't work well because we'd have to do that for every conceivable node type somebody might stuff in here.

[bitprophet]

Might have to/be able to do something ultra horrid like subclass builder classes and modify this behavior in one form or another. Ideally what I need, as above, is just for everything to be consistent so it can then be consistently styled; alternately, for the "non first" items to be what get a special class.

[bitprophet]

I don't see any way to handle this that both avoids a styling requirement and won't break on nontrivial scenarios. So we need some styling.

I think I can use CSS3 for this and neatly solve it:

div#changelog > div.section > ul > li > p:only-child {
    margin-bottom: 0;
}

Only downside here (and it's possible this was why the docutils behavior was added) is that subsequent paragraphs within list-items might not be immediately obviously related to the previous ones (especially if the multi-para list item is the last one in its list.)

However I think it's clear enough, at least under the Alabaster theme, and is at least consistent everywhere. Ideally we'd have some cute little vertical line or other way of associating the items, but meh.

[bitprophet]

So that works and the test suite finally passes fully again. Confirmed bugfix as well by reverting impl while preserving test suite, and the new test re: complex issue bodies does fail