search

swiftlang / swift-docc

Documentation compiler that produces rich API reference documentation and interactive tutorials for your Swift framework or package.
https://swift.org/documentation/docc
Apache License 2.0
1.17k stars 123 forks source link

Line numbers in code listings #737

Open DavidBrunow opened 11 months ago

DavidBrunow commented 11 months ago

Feature Name

Line numbers in code listings

Description

I'd like the ability to optionally show line numbers in code listings.

Motivation

This would be helpful to me when writing documentation around a code listing in order to explain the code. Being able to say "on line 5" without the reader needing to count to line 5 would allow the documentation to be more clear.

Importance

I don't think this is a super important feature but I do believe that it would improve the user experience for folks reading documentation.

Alternatives Considered

My current workaround is to refer to the symbols in the code listing by name in the documentation surrounding the code listing.

natikgadzhi commented 10 months ago

@ethan-kusters that should probably also be in docc-render? I think it's relatively easy to do, too.

natikgadzhi commented 10 months ago

I'm taking a look ;) So the good news is CodeListing can show line numbers.

We just need to figure out how to best tell it to show line numbers, and what level of flexibility we want. If I read the code correctly, it looks for contentNode.showLineNumbers for contentNodes that are codeListing.

So hypothetically, we could do a few things here:

  1. Add an option like @CodeListingsShowLineNumbers(true) or similar. Options are usually scoped to the current page / article, and it feels janky.
  2. See if we can change how we parse the ``` code block syntax to accept something like ``` showLineNumbers, similar to https://rehype-pretty-code.netlify.app/ on a level of a specific code block. That will be more involved, likely require some hacking in swift-markdown, BUT that will allow others to use that, too.
  3. Make site-wide setting and pass it in an env variable or a build flag. That's probably a crappy option because those are obscure, and it will be difficult to document.

I feel like option 2 is what's generally expected with markdown-base documentation systems.

Anthony-Eid commented 7 months ago

Would this be a good second issue for me to take a look at? I'm trying to learn more about this code base and would love to have something to do while I'm waiting on feedback from my pull request.

Admittedly, I'm probably going to need some guidence with attacking this issue, but I'm eager to give it my best shot. 😀