SF.net SVN: docutils:[10293] trunk/docutils

Revision: 10293
          http://sourceforge.net/p/docutils/code/10293
Author:   milde
Date:     2026-01-21 15:18:32 +0000 (Wed, 21 Jan 2026)
Log Message:
-----------
Fix :number-lines: option of the "include" directive.

Fix Sphinx issue #14261: ":number-lines: 0 for includes does not work correctly".

Commit [r9909] changed the conversion function to return "None" or an integer.
The former simple test for an optional start value failed for value 0,
because bool("0") == True but bool(0) == False.

Use the conversion function `value_or((None,), int)` also in the Code directive.

Modified Paths:
--------------
    trunk/docutils/HISTORY.rst
    trunk/docutils/docutils/parsers/rst/directives/body.py
    trunk/docutils/docutils/parsers/rst/directives/misc.py
    trunk/docutils/test/test_parsers/test_rst/test_directives/test_include.py

Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst	2026-01-15 22:33:54 UTC (rev 10292)
+++ trunk/docutils/HISTORY.rst	2026-01-21 15:18:32 UTC (rev 10293)
@@ -25,6 +25,8 @@
 
   - "Include" options :start-after: and :end-before: may now also
     be used without value (standing for an empty line).
+  - Fix Sphinx issue #14261:
+    The "Include" option :number-lines: changed a start value 0 to 1.
   - The severity of "include" problems is lowered to 3: ERROR.
 
 * docutils/parsers/rst/directives/tables.py,

Modified: trunk/docutils/docutils/parsers/rst/directives/body.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/directives/body.py	2026-01-15 22:33:54 UTC (rev 10292)
+++ trunk/docutils/docutils/parsers/rst/directives/body.py	2026-01-21 15:18:32 UTC (rev 10293)
@@ -157,7 +157,7 @@
     optional_arguments = 1
     option_spec = {'class': directives.class_option,
                    'name': directives.unchanged,
-                   'number-lines': directives.unchanged  # integer or None
+                   'number-lines': directives.value_or((None,), int),
                    }
     has_content = True
 
@@ -186,11 +186,9 @@
                 raise self.warning(error)
 
         if 'number-lines' in options:
-            # optional argument `startline`, defaults to 1
-            try:
-                startline = int(options['number-lines'] or 1)
-            except ValueError:
-                raise self.error(':number-lines: with non-integer start value')
+            startline = self.options['number-lines']
+            if startline is None:
+                startline = 1
             endline = startline + len(self.content)
             # add linenumber filter:
             tokens = NumberLines(tokens, startline, endline)

Modified: trunk/docutils/docutils/parsers/rst/directives/misc.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/directives/misc.py	2026-01-15 22:33:54 UTC (rev 10292)
+++ trunk/docutils/docutils/parsers/rst/directives/misc.py	2026-01-21 15:18:32 UTC (rev 10293)
@@ -181,7 +181,9 @@
         literal_block.line = self.options.get('start-line', 0) + 1
         self.add_name(literal_block)
         if 'number-lines' in self.options:
-            firstline = self.options['number-lines'] or 1
+            firstline = self.options['number-lines']
+            if firstline is None:
+                firstline = 1
             text = text.removesuffix('\n')
             lastline = firstline + len(text.splitlines())
             tokens = NumberLines([([], text)], firstline, lastline)

Modified: trunk/docutils/test/test_parsers/test_rst/test_directives/test_include.py
===================================================================
--- trunk/docutils/test/test_parsers/test_rst/test_directives/test_include.py	2026-01-15 22:33:54 UTC (rev 10292)
+++ trunk/docutils/test/test_parsers/test_rst/test_directives/test_include.py	2026-01-21 15:18:32 UTC (rev 10293)
@@ -210,6 +210,26 @@
         This file is used by ``test_include.py``.
 """],
 [f"""\
+Literal include, add line numbers
+
+.. include:: {include1}
+   :literal:
+   :start-line: 2
+   :number-lines: 0
+""",
+f"""\
+<document source="test data">
+    <paragraph>
+        Literal include, add line numbers
+    <literal_block source="{include1}" xml:space="preserve">
+        <inline classes="ln">
+            0 \n\
+        \n\
+        <inline classes="ln">
+            1 \n\
+        This file is used by ``test_include.py``.
+"""],
+[f"""\
 Include code
 
 .. include:: {include1}
@@ -1157,7 +1177,7 @@
 
 .. include:: {include1}
    :code: rst
-   :number-lines:
+   :number-lines: 0
 """,
 f"""\
 <document source="test data">
@@ -1165,21 +1185,21 @@
         Included code
     <literal_block classes="code rst" source="{include1}" xml:space="preserve">
         <inline classes="ln">
-            1 \n\
+            0 \n\
         <inline classes="generic heading">
             Inclusion 1
         \n\
         <inline classes="ln">
-            2 \n\
+            1 \n\
         <inline classes="generic heading">
             -----------
         \n\
         <inline classes="ln">
-            3 \n\
+            2 \n\
         <inline classes="whitespace">
             \n\
         <inline classes="ln">
-            4 \n\
+            3 \n\
         <inline classes="whitespace">
         This file is used by \n\
         <inline classes="literal string">

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.