search

pdoc3 / pdoc

:snake: :arrow_right: :scroll: Auto-generate API documentation for Python projects
https://pdoc3.github.io/pdoc/
GNU Affero General Public License v3.0
1.13k stars 146 forks source link

wrong start_line parameter in git link templates for module docstrings #296

Closed eladyn closed 3 years ago

eladyn commented 3 years ago

Expected Behavior

The generated "BROWSE GIT" link for a module should be generated with start_line = 1 and end_line similarly with the correct last line number.

Actual Behavior

It is generated with start_line = 0 and end_line correspondingly with the last linenumber reduced by 1.

Steps to Reproduce

  1. Go to https://pdoc3.github.io/pdoc/doc/pdoc/cli.html
  2. Click on "BROWSE GIT"-link beneath the module docstring. (for me it leads to https://github.com/pdoc3/pdoc/blob/0658ff01d8e218fcf67ee3f313bef6875c75f0ae/pdoc/cli.py#L0-L595)
  3. Scroll to the bottom of the file and notice the last line that is not highlighted.

Additional info

Every class, function, method or variable docstrings "BROWSE GIT"-link I have tried yet worked, so it seems to be specific to the module docstrings.

kernc commented 3 years ago

Thanks for the clear bug report. The issue seems to be the -1 here: https://github.com/pdoc3/pdoc/blob/bec63077a03b2136e6982825d327073ed76cc20a/pdoc/html_helpers.py#L563-L564 Not sure why, though. Welcome an investigation/PR.

eladyn commented 3 years ago

Thank you for the quick response.

I did some further investigation and it seems that the real problem is an undocumented behavior of the getsourcelines(object) function in the inspect module.

The docstring for this function says:

Return a list of source lines and starting line number for an object.

However, when looking through the source code of this function, I found: https://github.com/python/cpython/blob/39a7578186d2f5eaa112a5854c46f84eae401522/Lib/inspect.py#L1011-L1016

This causes the function to return 0 as start_line for modules and for other objects the real line number (which is done with lnum + 1).

I also found a similar looking thing in the findsource function which is called by getsourcelines()so it seems to be "intended" behavior.

Therefore, I think this could easily be fixed by adding a check like (I just tried it locally and it seems to be working)

if start_line == 0:
    start_line = 1

I can of course start a PR if you think that the above makes sense.

kernc commented 3 years ago

Python bug, the usual. Excellent detective work. start_line = start_line or 1 # GH-296 seems a reasonable fix on our end. :+1:

eladyn commented 3 years ago

Sorry for the late reply. Should I create a pull request for your fix or are you going to directly commit it to master?