docs: Refactor and add test for paginated_return_data.py

[kedod]

Description

• Refactor and add test for paginated_return_data doc example

Visible code shows the simpliest usage of the funcionality.
The Full code dropdown shows the full working example code with highlighted lines.

Closes

[kedod]

Maybe something more cool than Full code?
Any ideas?

[peterschutt]

I'm fine with Full Code - we should just be consistent everywhere. Have we done this anywhere else yet?

[kedod]

I have found this:

.. dropdown:: Full Code (click to expand)

I'm gonna change this to keep consistency.

[github-actions]

Documentation preview will be available shortly at https://litestar-org.github.io/litestar-docs-preview/3456

[peterschutt]

Thanks! I think the auto format might have thrown out the line numbers by one.

Do you think we should we use literal includes for the remaining code blocks in that section?

[peterschutt]

I'm fine with Full Code - we should just be consistent everywhere. Have we done this anywhere else yet?

[JacobCoffee]

im struggling with this because now we split into two places and increase maintenance burden around :linenos: upkeep but on the flip side I really hate scrolling through giant walls of code to get to the next section.

Aesthetically I would prefer the usage of sphinx-togglebutton. I think it looks a lot cleaner and is customizable. (https://shibuya.lepture.com/extensions/sphinx-togglebutton/)

Maybe we could standardize on just always showing full blocks of code, but if those are over a certain line count e.g., wont fit in half of the viewport or maybe the full length of the viewport then we chunk it into a .. dropdown::`` directive with :class: dropdown` to style it?

[kedod]

im struggling with this because now we split into two places and increase maintenance burden around :linenos: upkeep but on the flip side I really hate scrolling through giant walls of code to get to the next section.

Aesthetically I would prefer the usage of sphinx-togglebutton. I think it looks a lot cleaner and is customizable. (https://shibuya.lepture.com/extensions/sphinx-togglebutton/)

Maybe we could standardize on just always showing full blocks of code, but if those are over a certain line count e.g., wont fit in half of the viewport or maybe the full length of the viewport then we chunk it into a .. dropdown:: directive with ``:class: dropdown` to style it?

That's ok but I'm afraid that after examples rewrite (to make them self contained) the most of them will be too long to make them visible at start and "unhiding" every example can be user unfriendly too.
I have one more idea.
Custom extension

Let's say:

.. dropdownliteralinclude:: /examples/data_transfer_objects/factory/paginated_return_data.py
    :language: python
    :lines: 9-11,26-40

It can work similar to Slack. Take a look:

We can show only lines at start then highlight the same lines after expanding.
What do you think about this @JacobCoffee ?
For huge files we can still use togglebutton you suggested.

If you like this idea I can look for an extension or try to implement it on my own.

[sonarcloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarCloud