Display line numbers when viewing source code

[abubelinha]

Problem Description

Two related enhancement proposals:

1. Are there any chances to (optionally) display source code line numbers in html documentation?
2. Are there any chances to link to specific source code line numbers in html documentation?

Proposal

1. When you click view-source at the right side of a function definition (or Class, or whatever), source code lines are shown.
   Is it possible that these lines come with the line number shown on the left side? (as an option, like many text editors offer)
2. I noticed that each line of source code is rendered as a single <span class="sd">source code</span>
   If each span is preceded with a <a name="lnXXXX"> tag, then that line (number XXXX) would be linkable using module.html#lnXXXX

Alternatives

1. For showing line numbers:

• Offer this as an option in pdoc.render.configure(show_line_numbers: bool)
• Offer this as a clickable option in html output, next to view-source on the right side
• Offer both options

2. For introducing linking anchors:

• Offer this as an option in pdoc.render.configure(create_line_anchors: bool)
  Probably this would imply that view-source should be active by default in rendered html output as well, not needing to click anywhere (otherwise, module.html#lnXXXX links to specific span tag anchors won't do anything if those span tags are not already visible when module.html is loaded).

Additional context

https://pdoc.dev/docs/pdoc/render.html#configure
https://pdoc.dev/docs/pdoc/doc.html#Doc.source_lines
Useful to complement use case described in #325 and specially in #327

[mhils]

I think line numbers should be generally useful for everyone, no need to make it an option. There are line numbers on GitHub as well and you cannot configure it. :)

I've implemented the necessary changes in main...mhils:linenumbers, but we first need to wait for a pygments fix to ship in pygments/pygments#2026.

[abubelinha]

Sounds great, but as you changed the title (no mention to links now) I am a bit confused.
Will these changes also include 2nd proposal (linking to specific lines)?
If so, will source lines be shown without user interaction, after clicking the link? (i.e. not needing additional "view-source" click).

The "option" proposal was because file sizes will increase when adding line numbers (and even more with link anchors). Probably not a problem for anyone (not for me).

[mhils]

Yes, line numbers are clickable and should auto-expand. :)

[abubelinha]

I would like to add something else related to source code readability.
I believe this is probably just a CSS question but I don't really know how to modify templates to achieve this.

Is it possible to wrap long lines of source code so they continue on the next line, instead of current overflowing below the right border? I mean really long lines (at least 80 characters, and only if they overflow).
Now that lines will have numbers, this shouldn't create confusion and would increase readability.

Many could say my source code should already contain line breaks, but sometimes it's not that simple:

• My screen and/or my text editor could be wider than pdoc's html documents. Their font sizes could also be different.
• Many parts of my code could have been taken from other people.
• Probably it's not a good idea to modify source code because of this, especially if documentation software (pdoc or any other) can solve it.

[abubelinha]

I've implemented the necessary changes in main...mhils:linenumbers, but we first need to wait for a pygments fix to ship in pygments/pygments#2026.

How long do you expect that wait can be?
Just curious. I am checking this issue weekly but I don't know if I can configure some sort of notification for things like this (sorry, I am certainly not a github expert)

[mhils]

How long do you expect that wait can be?

The PR has been merged, so it will be part of the next pygments release. I don't think there's any urgency and we shouldn't bother them with it. They seem to do frequent releases, and we can wait for their regular next one. :)

[abubelinha]

I’m afraid you got me wrong. I wasn’t trying to force any pdoc changes with my comments in #343
I only wanted to share the solution I had found for my problem (originally stated above in this issue). So other newbies like me could find it useful.
Please acept my apologies, it wasn’t necesary to answer me any further or locking conversation (there were no pending questions, actually).

Sorry again