Add a 'language' option to customize output language

CHANGES.rst

@@ -11,6 +11,7 @@
   namespace package.
 - Now requires docutils >= 0.18.1. This effectively requires Sphinx
   versions newer than 5.0.
+- Add the ``language`` option. Added in :pr:`62` by Even Rouault.
 
 
 0.17 (2021-03-31)

doc/index.rst

@@ -231,6 +231,14 @@ Reference
    .. versionchanged:: 0.16
       Add the ``caption`` and ``name`` options.
 
+   A ``language`` option can be given to specify the language of the output.
+   This can be set for example to ``json`` for a program whose output is JSON.
+   In that case, this must only be used with the :dir:`program-output` directive,
+   and not :dir:`command-output`.
+
+   .. versionchanged:: 0.18
+      Add the ``language`` option.
+
 .. directive:: command-output
 
    Same as :dir:`program-output`, but with enabled ``prompt`` option.

src/sphinxcontrib/programoutput/__init__.py

@@ -92,7 +92,8 @@ class ProgramOutputDirective(rst.Directive):
     option_spec = dict(shell=flag, prompt=flag, nostderr=flag,
                        ellipsis=_slice, extraargs=unchanged,
                        returncode=nonnegative_int, cwd=unchanged,
-                       caption=unchanged, name=unchanged)
+                       caption=unchanged, name=unchanged,
+                       language=unchanged)
 
     def run(self):
         env = self.state.document.settings.env
@@ -112,6 +113,7 @@ def run(self):
         node['working_directory'] = cwd
         node['use_shell'] = 'shell' in self.options
         node['returncode'] = self.options.get('returncode', 0)
+        node['language'] = self.options.get('language', 'text')
         if 'ellipsis' in self.options:
             node['strip_lines'] = self.options['ellipsis']
         if 'caption' in self.options:
@@ -312,7 +314,7 @@ def run_programs(app, doctree):
                 )
 
             new_node = node_class(output, output)
-            new_node['language'] = 'text'
+            new_node['language'] = node['language']
             node.replace_self(new_node)
 
 

src/sphinxcontrib/programoutput/tests/test_directive.py

@@ -440,6 +440,17 @@ def test_name_with_caption(self):
         self.assert_cache(self.app, 'echo spam', 'spam')
 
 
+    @with_content("""\
+    .. program-output:: python -c 'import json; d = {"foo": "bar"}; print(json.dumps(d))'
+       :language: json""",
+                  ignore_warnings=False)
+    def test_language_json(self):
+        literal = self.doctree.next_node(literal_block)
+        self.assertTrue(literal)
+        self.assertEqual(literal.astext(), '{"foo": "bar"}')
+        self.assertEqual(literal["language"], "json")
+
+
 def test_suite():
     return unittest.defaultTestLoader.loadTestsFromName(__name__)