Use original line numbering when using pyobject include

[saurabheights]

Describe the bug

This issue is similar to #1583 but when using pyobject.

I did a quick test with latest sphinx version, used a simply python file with main method at line 4-5. Instead of showing line number 4-5, sphinx shows line number 1,2.

I can add :lineno-start: 4 to fix line number but that defeats the advantage pyobject brings, i.e. as long as function name and behaviour doesnt change, including whole method is the right thing to do in the docs and any changes in file before the method should automatically fix the line numbers.

print("Test")


def main():
    print("main at line 5")


if __name__ == "__main__":
    main()

The result is

How to Reproduce

Index.rst

.. asas documentation master file, created by
   sphinx-quickstart on Mon Aug 28 22:25:07 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to asas's documentation!
================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

.. literalinclude:: ../line_width.py
    :language: python
    :pyobject: main
    :linenos:
    :lineno-start: 3


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

line_width.py

print("Test")


def main():
    print("main at line 5")


if __name__ == "__main__":
    main()

Environment Information

Platform:              linux; (Linux-6.2.0-26-generic-x86_64-with-glibc2.35)
Python version:        3.10.11 (main, May 16 2023, 00:28:57) [GCC 11.2.0])
Python implementation: CPython
Sphinx version:        7.1.2
Docutils version:      0.20.1
Jinja2 version:        3.1.2
Pygments version:      2.15.1

Sphinx extensions

No extension used. Autogenerate conf.py file, no change done there.

Additional context

No response

[picnixz]

In your rst, you have the :lineno-start: so I am assuming that the latter works (I cannot reproduce it because I don't have access to my computer now). By looking around the code, it appears that you should use :lineno-match: in order for the line number to be displayed as you want but I acknowledge that this is not explained.

[saurabheights]

@picnixz Thank you. This worked perfectly.

[picnixz]

I'll assign myself to the issue so that I remember I need to update the docs.

[saurabheights]

@picnixz A follow-up question. Is it possible to make prepend option work with linenos-match? linenos-match requires code to be consecutive but shouldn't ops like append/prepend act on generated docs.

[picnixz]

I don't know. I can look at it at some point.

[saurabheights]

Is it possible to make prepend option work with linenos-match?

Just adding cross-link, this was needed in open3d to reference filename with the python code. isl-org/Open3D#6321 (comment)

[picnixz]

Actually the docs says:

When specifying particular parts of a file to display, it can be useful to display the original line numbers. This can be done using the lineno-match option, which is however allowed only when the selection consists of contiguous lines.

So nothing to do I think.

For prepend/append, it appears that the lines are correctly inserted. What do you mean then by "it doesn't work"? Can you give me what are the options you are using?

[picnixz]

Ah ok, actually the option pair is just not supported (explicitly rejected). We could implement some support but then, what would be the line start if you prepend something?

[saurabheights]

Yeah, I dont have a good answer for it. I have for example usecase of Open3D, but that is not generic enough for all sphinx users. It would be good to collect other opinions before going for a solution.

P.S. For my usecase, prepend means prepend with some text. It should preferrably not have any line number.