Proper text wrapping of long descriptions

[tomghyselinck]

Hi,

We like this project very much!

One thing which makes documentation hard to read for our users is when the description contains long lines of text.

It seems that those are not properly wrapped (like is done in a normal section in sphinx documentation).
Instead we get a scroll bar below the schema. For large schema's this becomes quite cumbersome to read the documentation:

• read a part,
• scroll down below the schema,
• scroll the schema right,
• scroll up back to the part you were reading
• and again for the next part of the line

For example:

• https://api.byteblower.com/test-framework/v1.2.0/byteblower-test-framework/config/index.html#frame-blasting-flow
• https://api.byteblower.com/test-framework/v1.2.0/byteblower-test-framework/config/index.html#configuration-parameters-for-a-byteblower-port-or-endpoint

Can you tell us how to avoid this? Is there some styling (CSS?) parameter we can add / change to our documentation? Is there a different option we can set?

[lnoor]

Thank you for the compliment.
I am pleased to hear it is of use to you.

A schema is rendered by creating a grid table for it.
So it is turned in a set of rows with cells each containing one item.

Thus a schema is transformed into

+--------------------------------------------------------------------------------------- +
|Configuration parameters for a ByteBlower Port or ...             |
+=================================================+
|Configuration parameters for a ByteBlower Port or ...            |
+---------------------+----------------------------------------------------------------+
| type                 | object                                                                   |
+--------------------+---------------------------------------------------------------- +
| properties                                                                                        |
+--------------------+-----------------------------------------------------------------+
| - name            | Name of this ByteBlower traffic endpoint ... |
|                         +--------+-------------------------------------------------------+
|                         | type | string                                                        |
+--------------------+--------+------------------------------------------------------+
| - port_group | List of port group where this port belong... |
|                        +-------+--------------------------------------------------------+
|                       | type | array                                                           |
+------------------+---------+-------------------------------------------------------+

(didn't check for validity, I'm sure you understand what I'm trying to say).

In fact all parts of a schema are expressed using existing reStructuredText elements.
So it becomes just a plain table that can be styled as your other tables.
Unless you have defined custom css classes for your tables.

There is no support assigning css classes to individual tables.
The reason is that I needed the result to be renderable to epub and pdf as well as the web.

I had the same problem as you and my solution is to make extensive use of $ref references and having anchors and links to let the viewer jump to the definition of the reference.
That way I could 'flatten' the depth of the tree so it also looks good on a printed page.

One thing I do not really understand is why the regular text in the descriptions isn't wrapped within the available width.
Did you disable wrapping using css?

I'm sorry I cannot be of more help at the moment.

[tomghyselinck]

Hi @lnoor,

Thank you for the extended information!

We are indeed already using $ref extensively too (well, as long as relevant to split off).

We have a custom CSS, but as far as I know, text wrapping shouldn't be disabled.
I will have a look to be sure.
But that is indeed our main issue at the moment, I'll get back to this if I have a better clue on what is going wrong here.

With best regards,
Tom.

[tomghyselinck]

Hi @lnoor,

FYI: I found and solved the issue: It was related to the sphinx-rtd-theme: readthedocs/sphinx_rtd_theme#1246

See also https://stackoverflow.com/questions/69359978/grid-table-does-not-word-wrap

[lnoor]

Hi @tomghyselinck,

I'm glad you found the cause and a work-around.
I will then close this ticket.
Feel free to reopen if you see any reason to do so.

With regards,
Leo