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.

[picnixz]

Unfortunately, not putting line numbers would be more tricky because the highlight is done by Pygments and not Sphinx. So maybe there are pygments options for that but otherwise, pretending lines would require the line numbers.

Btw, can't you actually use :caption: instead for your specific use case? (possibly with changing the CSS for a better captioning?)

[saurabheights]

Yes caption works but needs CSS update, but that should be easy now. Thank you so much.

I am not sure if you still would like to make prepend work with linenos-match, so you can decide to keep this issue open or close it.

[picnixz]

I can make it work, but lines won't be numbered as you would expect. But it'll be a low priority task imho.

I'll ask the maintainer upon my return.

[picnixz]

So, I asked myself and I think I won't work on this one unless more people want it (and thus I'm unassigning myself from this issue). Also, from a personal PoV, I think that if someone wants to include non-numbered lines, then it should be outside the pyobject include directive. For me 'prepend' really means prepending something as if it were directly in the included portion of the code.

For now, I will close this specific issue and if someone wants the feature of 'prepend without no lineno', a new issue should be opened.