Strip function definition in literalinclude -> pyobject

[Dreamsorcerer]

Is your feature request related to a problem? Please describe.
Simple examples in docs tend to get out of sync with APIs etc. To fix this, we want to type check that code with mypy.

The only properly maintainable way to include such code would be using the literalinclude directive with pyobject (e.g. to ensure we don't miss line number changes etc.). To use pyobject, we need to put the code into a function (we'd probably need to do that because it's mostly async code anyway).

This results in simple examples all appearing with a function signature which is not relevant to the example. So, we'd like to see a directive that excludes the function signature.

Describe the solution you'd like

async def intro_example():
    async with ClientSession() as session:
        async with session.get("/path") as resp:
            print(resp.status)

In the docs, something like:

Usage example:

.. literalinclude: docs_examples.py
   :pyobject: intro_example
   :strip-def:
   :dedent:

Resulting in rendering like:

Usage example:

async with ClientSession() as session:
    async with session.get("/path") as resp:
        print(resp.status)

Describe alternatives you've considered
I can't see any alternatives that are worth doing. Will likely just leave the code in the docs until a solution like this is provided.

[AA-Turner]

Hi Sam,

Thanks for creating the issue.

Out of interest, who is 'we'? Would be useful to know how widespread something like this would be.

I wonder if an option would be to make :lines: work with :pyobject:, to select lines relative to the definition line. That would be more flexible than just removing the definition, though might need consideration w.r.t. indentation.

A

[Dreamsorcerer]

Out of interest, who is 'we'? Would be useful to know how widespread something like this would be.

aio-libs in this case. Starting with all the examples in aiohttp: https://docs.aiohttp.org/en/stable/

I wonder if an option would be to make :lines: work with :pyobject:, to select lines relative to the definition line. That would be more flexible than just removing the definition, though might need consideration w.r.t. indentation.

That would probably be good enough for us, though it's not quite as maintainable in the sense that if a function signature changes and gets wrapped over multiple lines, it would now appear in the docs until someone noticed (or the reverse, where a couple of lines disappears from the docs).

[Dreamsorcerer]

not quite as maintainable

Thinking that through, for our case we'd basically just be wrapping them in a basic function that serves no other purpose. So, the function signature is very unlikely to change after being created. So, this would work perfectly fine.

[Dreamsorcerer]

As an example, we just merged this:
https://docs.aiohttp.org/en/latest/client_middleware_cookbook.html#token-refresh-middleware

I'd like the 3rd example in that section to be rendered without the function def. If we get this feature, we'll then want to extract all existing code blocks from the docs in future and do the same thing.