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

[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?

[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.

[sonarqubecloud]

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

[provinzkraut]

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?

I have a quite strong opinions on the dropdowns in that I think they should almost always be avoided in reference docs when they're hiding code. The code is what these docs are talking about, so hiding it is simply obscuring one of the main pieces of information.

@JacobCoffee If you don't like scrolling, we should improve the section layout / side nav. But hiding code is the worst option IMO.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud