feat(docs): migrate from .md to .rst (#4129)

docs/widgets/span.rst

@@ -0,0 +1,127 @@
+Span (lv_span)
+==============
+
+Overview
+********
+
+A spangroup is the object that is used to display rich text. Different
+from the label object, ``spangroup`` can render text styled with
+different fonts, colors, and sizes into the spangroup object.
+
+Parts and Styles
+****************
+
+-  :cpp:enumerator:`LV_PART_MAIN` The spangroup has only one part.
+
+Usage
+*****
+
+Set text and style
+------------------
+
+The spangroup object uses span to describe text and text style. so,
+first we need to create ``span`` descriptor using ``lv_span_t * span = lv_spangroup_new_span(spangroup)``.
+Then use :cpp:expr:`lv_span_set_text(span, "text")` to set text. The style of the span is
+configured as with a normal style object by using its ``style`` member,
+eg::cpp:expr:`lv_style_set_text_color(&span->style, lv_palette_main(LV_PALETTE_RED))`.
+
+If spangroup object ``mode != LV_SPAN_MODE_FIXED`` you must call
+:cpp:func:`lv_spangroup_refr_mode` after you have modified ``span``
+style(eg:set text, changed the font size, del span).
+
+Retrieving a span child
+-----------------------
+
+Spangroups store their children differently from normal objects, so
+normal functions for getting children won’t work.
+
+:cpp:expr:`lv_spangroup_get_child(spangroup, id)` will return a pointer to the
+child span at index ``id``. In addition, ``id`` can be negative to index
+from the end of the spangroup where ``-1`` is the youngest child, ``-2``
+is second youngest, etc.
+
+e.g. ``lv_span_t* span = lv_spangroup_get_child(spangroup, 0)`` will
+return the first child of the spangroup.
+``lv_span_t* span = lv_spangroup_get_child(spangroup, -1)`` will return
+the last (or most recent) child.
+
+Child Count
+-----------
+
+Use the function :cpp:expr:`lv_spangroup_get_child_cnt(spangroup)` to get back
+the number of spans the group is maintaining.
+
+e.g. ``uint32_t size = lv_spangroup_get_child_cnt(spangroup)``
+
+Text align
+----------
+
+like label object, the spangroup can be set to one the following modes:
+
+- :cpp:enumerator:`LV_TEXT_ALIGN_LEFT` Align text to left.
+- :cpp:enumerator:`LV_TEXT_ALIGN_CENTER` Align text to center.
+- :cpp:enumerator:`LV_TEXT_ALIGN_RIGHT` Align text to right.
+- :cpp:enumerator:`LV_TEXT_ALIGN_AUTO` Align text auto.
+
+use function :cpp:expr:`lv_spangroup_set_align(spangroup, LV_TEXT_ALIGN_CENTER)`
+to set text align.
+
+Modes
+-----
+
+The spangroup can be set to one the following modes:
+
+- :cpp:enumerator:`LV_SPAN_MODE_FIXED` fixes the object size.
+- :cpp:enumerator:`LV_SPAN_MODE_EXPAND` Expand the object size to the text size but stay on a single line.
+- :cpp:enumerator:`LV_SPAN_MODE_BREAK` Keep width, break the too long lines and auto expand height.
+
+Use :cpp:expr:`lv_spangroup_set_mode(spangroup, LV_SPAN_MODE_BREAK)` to set
+object mode.
+
+Overflow
+--------
+
+The spangroup can be set to one the following modes:
+
+- :cpp:enumerator:`LV_SPAN_OVERFLOW_CLIP` truncates the text at the limit of the area.
+- :cpp:enumerator:`LV_SPAN_OVERFLOW_ELLIPSIS` will display an ellipsis(``...``) when text overflows the area.
+
+Use :cpp:expr:`lv_spangroup_set_overflow(spangroup, LV_SPAN_OVERFLOW_CLIP)` to set object overflow mode.
+
+first line indent
+-----------------
+
+Use :cpp:expr:`lv_spangroup_set_indent(spangroup, 20)` to set the indent of the
+first line. all modes support pixel units, in addition to :cpp:enumerator:`LV_SPAN_MODE_FIXED`
+and :cpp:enumerator:`LV_SPAN_MODE_BREAK` mode supports percentage units
+too.
+
+lines
+-----
+
+Use :cpp:expr:`lv_spangroup_set_lines(spangroup, 10)` to set the maximum number
+of lines to be displayed in LV_SPAN_MODE_BREAK mode, negative values
+indicate no limit.
+
+Events
+******
+
+No special events are sent by this widget.
+
+Learn more about :ref:`events`.
+
+Keys
+****
+
+No *Keys* are processed by the object type.
+
+Learn more about :ref:`indev_keys`.
+
+Example
+*******
+
+
+.. include:: ../examples/widgets/span/index.rst
+
+API
+***