Make rest2html work with docutils 0.13

Imported a PR https://github.com/github/markup/pull/976 reffered by @pravi in https://gitlab.com/gitlab-org/gitlab-markup/issues/5.

In that docutils version, HTMLTranslator.visit_image no longer appends
empty string to self.context, so trying to pop() from there raises an
IndexError.

Instead of the hard-coded pop call, call the overridden method, which will
call pop() on docutils 0.12 and will do nothing on docutils 0.13.

Also, fix the comment indentation.

cc @marin

@marin Do we keep docutils==0.12 in our tests and keep supporting it, should we jump to 0.13 and support both or only the latest?

marked as a Work In Progress

@brodock Are there any reasons why we would want to support both? We should aim to keep this as simple as possible.

@marin I don't know for sure, but maybe to help community packaging for specific distros.

@brodock Lets focus for now on supporting the latest, we can change our decision if necessary.

added 1 commit

• 941d6e9a - Update README and upgrade docutils in CI

Compare with previous version

unmarked as a Work In Progress

added Enhancement label

added 1 commit

• 3f07eb10 - Update README and upgrade docutils in CI

Compare with previous version

assigned to @marin

@pravi I will cut a release as soon as this gets merged, and update it in GitLab master

I’ve tested the diff:

With docutils 0.13 it now works fine (without this MR applied it doesn’t work):

% cat test.rst
.. image:: http://coucou
% python -c "import docutils; print(docutils.__version__)"
0.13.1
% ./rest2html test.rst
<img alt="http://coucou" src="http://coucou" />

However, if I install docutils 0.12, it now tracebacks (without this MR applied, it works):

% cat test.rst
.. image:: http://coucou
% python -c "import docutils; print(docutils.__version__)"
0.12
% ./rest2html test.rst
Traceback (most recent call last):
  File "./rest2html", line 196, in <module>
    sys.stdout.write("%s%s" % (main(), "\n"))
  File "./rest2html", line 182, in main
    parts = publish_parts(text, writer=writer, settings_overrides=SETTINGS)
  File "/home/gitlab/.local/lib/python2.7/site-packages/docutils/core.py", line 448, in publish_parts
    enable_exit_status=enable_exit_status)
  File "/home/gitlab/.local/lib/python2.7/site-packages/docutils/core.py", line 662, in publish_programmatically
    output = pub.publish(enable_exit_status=enable_exit_status)
  File "/home/gitlab/.local/lib/python2.7/site-packages/docutils/core.py", line 219, in publish
    output = self.writer.write(self.document, self.destination)
  File "/home/gitlab/.local/lib/python2.7/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/home/gitlab/.local/lib/python2.7/site-packages/docutils/writers/html4css1/__init__.py", line 176, in translate
    self.document.walkabout(visitor)
  File "/home/gitlab/.local/lib/python2.7/site-packages/docutils/nodes.py", line 187, in walkabout
    visitor.dispatch_departure(self)
  File "/home/gitlab/.local/lib/python2.7/site-packages/docutils/nodes.py", line 1895, in dispatch_departure
    return method(node)
  File "./rest2html", line 87, in depart_document
    HTMLTranslator.depart_document(self, node)
  File "/home/gitlab/.local/lib/python2.7/site-packages/docutils/writers/html4css1/__init__.py", line 786, in depart_document
    assert not self.context, 'len(context) = %s' % len(self.context)
AssertionError: len(context) = 1

Conclusion: this MR fixes rest2html with docutils 0.13 but it apparently breaks with docutils 0.12. You apparently decided not to support 0.12 anymore (from what I can read of the discussion above) so this should not be a blocker. I just wanted to let you know.

mentioned in issue gitlab-com/support-forum#943 (closed)

@louiz we use python3 by default in omnibus, can you please give another try with that version?

The fix also got merged/validated in GH: https://github.com/github/markup/commit/774bb322c47a8447d2be85a4a8b68f8918b4df06

merged

mentioned in commit 4758533f

The problem persists with GitLab 9.4.1 and docutils 0.13.

Rst rendering is functional @frispete. If you have a specific problem that you are noticing, please raise a new issue.