#208 On parse error, print text block when src=None

[Colin Marquardt]

I am using https://github.com/tox-dev/sphinx-argparse-cli to document my Python app's command line options.
When I have a formatting error in the help text of such a command line option, I am getting an error like the following:

None:5: ERROR: Unexpected indentation

With the patch below, I have a much better chance to find the offending piece of code by printing some context, like so:

None:5: ERROR: Unexpected indentation near text:
Foo
Bar

--- docutils/parsers/rst/states_orig.py     2024-01-04 14:46:37.402565000 +0100
+++ docutils/parsers/rst/states.py          2024-01-17 13:48:00.991420000 +0100
@@ -2793,8 +2793,16 @@
             block = self.state_machine.get_text_block(flush_left=True)
         except statemachine.UnexpectedIndentationError as err:
             block, src, srcline = err.args
-            msg = self.reporter.error('Unexpected indentation.',
-                                      source=src, line=srcline)
+            if src is None:
+                msg = self.reporter.error(
+                    'Unexpected indentation near text:\n' +
+                    ' '.join(list(context)) +
+                    '\n' +
+                    ' '.join(list(block)),
+                    source=src, line=srcline)
+            else:
+                msg = self.reporter.error('Unexpected indentation',
+                                          source=src, line=srcline)
         lines = context + list(block)
         paragraph, literalnext = self.paragraph(lines, startline)
         self.parent += paragraph

[Günter Milde]

Thank you for the suggestion and patch.
I downloaded and tested the "sphinx-argparse-cli" extension. With the patch and a deliberate rst syntax error in an argument description, running "make html" on a project printed, among a long list of warnings,

None:3: ERROR: Unexpected indentation near text:
output file, 
default:.
/usr/local/src/PyLit/doc/usage.txt:1: WARNING: Inline emphasis start-string without end-string.
/usr/local/src/PyLit/doc/usage.txt:81: ERROR: Unknown target name: "code".
/usr/local/src/PyLit/doc/build/html/examples/index.txt: WARNING: document isn't included in any toctree

I would still have to guess, that the offending input is from an argument description string of a program read in via the "sphinx-argparse" directive.

Other syntax problems are reported with the source file containing the "sphinx_argparse_cli" directive but an "arbitrary" wrong line number, e.g.,

/usr/local/src/PyLit/doc/usage.txt:1: WARNING: Inline emphasis start-string without end-string.
/usr/local/src/PyLit/doc/usage.txt:81: ERROR: Unknown target name: "code".

A real improvement would be if "sphinx_argparse_cli" could handle the exception and turn it into a helpful error message that is both, reported on stderr and appended to the doctree at the place of occurence similar to what other directives do in case of syntax errors (i.e. return a "system_message" node). The "source" and line arguments for the reporter could be made the location of the .. sphinx_argparse_cli:: or a source description like "{prog} cli description".

I suggest reporting the issue there.