msabramo/docutils — pull request #1 by msabramo (2014-12-17 06:42:49+00:00)
Title: Hack for distutils check --restructuredtext

A Python distutils bug (http://bugs.python.org/issue23063) causes
`python setup.py check --restructuredtext` to fail on documents with
code blocks.

Fixes: SF-270 (https://sourceforge.net/p/docutils/bugs/270/)

----

`python setup.py check --restructuredtext --strict --metadata` fails with:

warning: check: Could not finish the parsing.

if the RST document uses `code` or `code-block` directives.

This is annoying because the document is valid, but it appears to be invalid and confuses people. For an example, see https://github.com/ionelmc/pytest-benchmark/pull/4#issuecomment-66940307.

How to reproduce this bug
-------------------------

Clone a repo that has a `README.rst` with `code-block` directives in it. E.g.:

```bash
$ git clone git@github.com:ionelmc/pytest-benchmark.git
$ cd pytest-benchmark
$ git checkout ab0b08f6fccb06a7909905a8409f8faa8b01e0d8
```

Observe that it has "code-blocks" in it:

$ grep 'code-block' README.rst
.. code-block:: python
.. code-block:: python

Observe that RST document is valid, according to `rst2html.py`:

$ rst2html.py --halt=1 README.rst > README.html && echo "RST was OK."
RST was OK.

$ head -n 3 README.html

Observe that `python setup.py check --restructuredtext --strict --metadata` fails:

$ python setup.py check --restructuredtext --strict --metadata
running check
warning: check: Could not finish the parsing.

error: Please correct your package.

$ echo $?
1

**What was expected**: `python setup.py check --restructuredtext --strict
--metadata` should succeed with no warnings, just as `rst2html.py did`, because
`README.rst` is a valid RST document.

**What actually happened**: `python setup.py check --restructuredtext --strict
--metadata` prints a warning and an error and fails, unlike `rst2html.py`

The error is coming from here:
https://github.com/python/cpython/blob/master/Lib/distutils/command/check.py#L142

It's happening because of this line:
https://github.com/python/cpython/blob/master/Lib/distutils/command/check.py#L125

```python
settings = frontend.OptionParser().get_default_values()
```

If this is changed to:

```python
settings = frontend.OptionParser(components=(Parser,)).get_default_values()
```

then things work much better (this is how `tools/quicktest.py` does it for example)

so this *might* actually be a bug in distutils, but changing CPython (and maybe PyPy) is a more laborious and slow process, so I'm thinking it might be nice to work around this in docutils, if isn't too much of a burden. Docutils is on a much shorter release cycle than CPython, so changing docutils is a way to get this fix out to users much faster.