From 6b982a3698d420bc9244a5806b92cea64d8e84df Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Wed, 6 Nov 2024 02:38:13 -0700 Subject: [PATCH] feat(docs): plea for proper word-wrapping in `.rst` files. (#7189) --- docs/README.md | 7 +++++++ docs/details/main-components/display.rst | 24 ++++++++++++++++-------- 2 files changed, 23 insertions(+), 8 deletions(-) diff --git a/docs/README.md b/docs/README.md index 071b5f56e..2693001c5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -63,6 +63,11 @@ If this is *not* appropriate for the .RST file you are creating, ensure the stem In alignment with the above, use a file name stem that is appropriate to the topic being covered. +### Text Format + +While with `.md` files, it is important to allow paragraphs to flow off to the right with one long line so that when they are formatted as `.html` files, the paragraphs will word-wrap with the width of the browser, this is not true with reStructuredText (`.rst` files). [Sphinx](https://www.sphinx-doc.org/en/master/) and its underlying [docutils parsing engine](https://docutils.sourceforge.io/docs/) conveniently combine grouped text into a proper paragraph with that word-wrapping behavior. This allows the source text documents to be nicely word-wrapped so that they are more readable in text- and code-editors that do not have wide editing windows. So please wrap the text around column 86 or narrower. Wrapping at *exactly* column 86 is not important, but readability and ease of editing is. + + ### index.rst Files If you create a new directory you MUST have an `index.rst` file in that directory and that index file needs to be pointed to in the `index.rst` file that is located in the parent directory. @@ -268,3 +273,5 @@ For such examples, simply use reStructuredText literal markup like this: ``lv_obj_set_layout((lv_obj_t *)widget, LV_LAYOUT_FLEX)`` ``lv_obj_set_layout(&widget, LV_LAYOUT_FLEX);`` ``lv_obj_set_layout(widget, ...)`` + + diff --git a/docs/details/main-components/display.rst b/docs/details/main-components/display.rst index b14500c83..22715cbcf 100644 --- a/docs/details/main-components/display.rst +++ b/docs/details/main-components/display.rst @@ -488,12 +488,19 @@ meaning ``(horizontal_resolution x vertical_resolution / 8) + 8`` bytes. As LVGL can not handle fractional width make sure to round the horizontal resolution to 8 bits (for example 90 to 96). -The :cpp:func:`lv_draw_sw_i1_convert_to_vtiled` function is used to convert a draw buffer in I1 color format from a row-wise (htiled) to a column-wise (vtiled) buffer layout. -This conversion is necessary for certain display controllers that require a different draw buffer mapping. The function assumes that the buffer width and height are rounded to a multiple of 8. -The bit order of the resulting vtiled buffer can be specified using the `bit_order_lsb` parameter. -For more details, refer to the implementation in :cpp:func:`lv_draw_sw_i1_convert_to_vtiled` in :file:`src/draw/sw/lv_draw_sw.c`. +The :cpp:func:`lv_draw_sw_i1_convert_to_vtiled` function is used to convert a draw +buffer in I1 color format from a row-wise (htiled) to a column-wise (vtiled) buffer +layout. This conversion is necessary for certain display controllers that require a +different draw buffer mapping. The function assumes that the buffer width and height +are rounded to a multiple of 8. The bit order of the resulting vtiled buffer can be +specified using the `bit_order_lsb` parameter. -To ensure that the redrawn areas start and end on byte boundaries, you can add a rounder callback to your display driver. This callback will round the width and height to the nearest multiple of 8. +For more details, refer to the implementation in +:cpp:func:`lv_draw_sw_i1_convert_to_vtiled` in :file:`src/draw/sw/lv_draw_sw.c`. + +To ensure that the redrawn areas start and end on byte boundaries, you can add a +rounder callback to your display driver. This callback will round the width and +height to the nearest multiple of 8. Here is an example of how to implement and set a rounder callback: @@ -510,9 +517,10 @@ Here is an example of how to implement and set a rounder callback: lv_display_add_event_cb(display, my_rounder_cb, LV_EVENT_INVALIDATE_AREA, display); -In this example, the `my_rounder_cb` function rounds the coordinates of the redrawn area to the nearest multiple of 8. -The `x1` and `y1` coordinates are rounded down, while the `x2` and `y2` coordinates are rounded up. This ensures that the -width and height of the redrawn area are always multiples of 8. +In this example, the `my_rounder_cb` function rounds the coordinates of the redrawn +area to the nearest multiple of 8. The `x1` and `y1` coordinates are rounded down, +while the `x2` and `y2` coordinates are rounded up. This ensures that the width and +height of the redrawn area are always multiples of 8. Constraints on Redrawn Area ---------------------------