Add skipping literal blocks example to docs

[cmarqu]

This is a real PR for the documentation but it can show a problem with .. autolink-skip:: I think.

(I am setting .. highlight:: python to get automatic Python highlighting for the :: blocks in this document, and thus I have to explicitly mark up the language for the non-Python literal blocks. This has probably nothing to do with the problem.)

The part that can trigger the bug is the new "Skipping literal blocks" subsection. It works fine if written like in this PR, but as soon as you remove the k1 = part (exactly this substring) from the example code, the code block in the section above suddenly gets linked, the the code block that had k1 = does not get linked anymore (which it should).

[felix-hilden]

That's a nice catch! It could be that we incorrectly match the HTML to the first block because it's the same code. Skipping looks to be short-circuiting it. The relevant bits are here and here - the latter controlling the set of code examples we attempt to match and potentially transform with links. So we'd have to move it up to happen always.

If you want to contribute the fix and make the doc entry a test instead that'd be lovely! If not, I'll get to it probably tomorrow 👍

But I'm not sure what Python syntax highlighting you'd be after as in the example page we have it already. The rST highligts are a nice touch though!

[cmarqu]

But I'm not sure what Python syntax highlighting you'd be after as in the example page we have it already.

In the example page there was no example with "implicit literal blocks", and I was not quite sure whether it would work to set .. autolink-skip:: before the paragraph, or if it would have to follow the :: that start the implicit literal block.
So it was a playground for me to test its behavior, and then I thought it would be useful for other readers as well. If you find it unnecessary, I'm happy to remove the section.

[cmarqu]

If you want to contribute the fix and make the doc entry a test instead that'd be lovely!

I don't have enough brain cycles left over today. :)

[felix-hilden]

Hah no worries! Yeah I was just talking about the explicit .. highlight: python which is not needed anymore 👌🏿

I committed the rst highlights and a better explanation of skipping next in the above commit. I though it would be better placed into the reference documentation as a concise note of how it works. Thanks for getting the ball rolling with it though! I'll see about the bug next.