Improve sphinx reStructuredText parsing

[krassowski]

This should largely fix pappasam/jedi-language-server#172.

[flaviut]

Is there code that handles any code blocks before this? Otherwise something like

.. code-block:: python
    def foo():
        """:param  str message_body: blah blah"""

could cause problems. I'll admit it's an edge case that would likely only come up in docstring parsing code.

[flaviut]

Oh, one other thing that comes to mind! If the programmer put these directives in a random order for some reason, it would be nice if all directives of a certain type were grouped together. Also definitely a bit of an edge case & not required, but there's plenty of less-than-finely crafted code out there.

[krassowski]

No, it will not cause problems. Code blocks are properly parsed out at an earlier stage. I added a test case in 1771df2 to demonstrate this.

[krassowski]

I agree about the order thing. That would require a proper parser though so we cannot just use regexp here. It is definitely in scope, but I don't have more time this weekend. Would you mind opening an issue so we can track this as a future improvement?

[flaviut]

resolved with #14

[flaviut]

Thanks for the link, and thanks for fixing this! I like the approach you've taken, I've used a similar approach in the past to convert markdown to HTML.