Allow showing only a range of lines for code blocks

[llucax]

Context

I'm using mkdocstrings and Sybil to extract code examples in the documentation and test by running pylint on them via pytest.

This forces me to sometimes add too much boilerplate to examples, which is distracting from the main idea I want to show in an example, but it is also really important that examples stay up to date and (mostly) working.

An alternative would be to move the examples to separate files and use the snippet extension line selection feature, but I want to keep the examples in the docstrings, so they are also accessible in code editors, as python include all the docs in the code itself.

Description

I would like code blocks to accept selecting which lines to show, similar to what the snippet extension or the highlight specific lines feature does. For example:

Example:
    ``` py show_lines="4:"
    # Bolierplate setup code
    # More boiler plate setup code
    # And some more
    this is the_juicy_part
    ```

I'm suggesting the snippet extension syntax (with :) instead of the highlight specific lines feature syntax because it is more natural for specifying open-ended ranges.

Related links

• Requesting a change
• Highlight specific lines feature
• Markdown Snippet extension line selection

Related discussions:

• User-defined copy range in code blocks #6252: Similar but only for selecting what to copy, not what to show.
• Focussable & Collapsible code blocks. #3944: Similar but it still includes the boilerplate code, it is just hidden. It would also require to add more noise to the example, and it looks like it might be harder to implement, as the code needs to be parsed too.

Extra:

• mkdocstrings
• sybil
• pylint
• pytest
• Code to put it all together

Use Cases

Being able to write examples that are verifiable using linting tools to ensure they stay up to date, but still only being able to show the relevant parts that make sense for the documentation, avoiding distracting, boilerplate code.

Visuals

It should look like a regular code block, just with less lines than the original code block.

Stretch goal: There could be some button to expand the example and show also the boilerplate code, so users could copy&paste the whole example and run it if they want.

Before submitting

• I have read and followed the change request guidelines.
• I have verified that my idea is a change request and not a bug report.
• I have ensured that, to the best of my knowledge, my idea will benefit the entire community.
• I have included relevant links to the documentation, related issues, and discussions to underline the need for my idea.

[squidfunk]

Thanks for suggesting! Please propose this to Python Markdown Extensions, as this is the library that converts code blocks into Markdown ☺️ Material for MkDocs only renders what it gets.

[llucax]

OK, I will do that, thanks. One question though, if the "button to expand the boilerplate option" would get implemented, would that need support from Material, or it would still be all part of pymdown-extensions?

[squidfunk]

Maybe, depends on the outcome.