✓ KivyMD. Development - Bounty program

[HeaTTheatR]

Due to the merger of the KivyMD library version 2.0.0 with the master branch, it is necessary to fix the build of the documentation on Readthedocs. We need to fix the documentation assembly in the 2.0.0 branch - https://github.com/kivymd/KivyMD/tree/2.0.0 and locally (build in a local repository). It is necessary that the documentation build be successful. At the moment, the documentation build fails both locally and on Github :(

The build is currently returning an exception:

cd docs
make html

Output:

Traceback (most recent call last):
  File "/sphinx/events.py", line 103, in emit
    results.append(listener.handler(self.app, *args))
  File "sphinx/environment/collectors/toctree.py", line 187, in process_doc
    toc = build_toc(doctree)
  File "sphinx/environment/collectors/toctree.py", line 107, in build_toc
    sub_item = build_toc(sectionnode, depth + 1)
  File "sphinx/environment/collectors/toctree.py", line 91, in build_toc
    nodetext = visitor.get_entry_text()
  File "docutils/transforms/parts.py", line 171, in get_entry_text
    return self.get_tree_copy().children
  File "docutils/nodes.py", line 2489, in get_tree_copy
    return self.parent[0]
IndexError: list index out of range

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "sphinx/cmd/build.py", line 455, in build_main
    app.build(args.force_all, args.filenames)
  File "sphinx/application.py", line 396, in build
    self.builder.build_update()
  File "phinx/builders/__init__.py", line 365, in build_update
    self.build(
  File "/sphinx/builders/__init__.py", line 387, in build
    updated_docnames = set(self.read())
  File "sphinx/builders/__init__.py", line 503, in read
    self._read_serial(docnames)
  File "sphinx/builders/__init__.py", line 531, in _read_serial
    self.read_doc(docname)
  File "sphinx/builders/__init__.py", line 596, in read_doc
    publisher.publish()
  File "docutils/core.py", line 277, in publish
    self.apply_transforms()
  File "docutils/core.py", line 245, in apply_transforms
    self.document.transformer.apply_transforms()
  File "sphinx/transforms/__init__.py", line 83, in apply_transforms
    super().apply_transforms()
  File "docutils/transforms/__init__.py", line 174, in apply_transforms
    transform.apply(**kwargs)
  File "sphinx/transforms/__init__.py", line 425, in apply
    self.app.emit("doctree-read", self.document)
  File "sphinx/application.py", line 537, in emit
    return self.events.emit(
  File "sphinx/events.py", line 114, in emit
    raise ExtensionError(
sphinx.errors.ExtensionError: Handler <bound method TocTreeCollector.process_doc of <sphinx.environment.collectors.toctree.TocTreeCollector object at 0x104448b20>> for event 'doctree-read' threw an exception (exception: list index out of range)

Extension error (sphinx.environment.collectors.toctree):
Handler <bound method TocTreeCollector.process_doc of <sphinx.environment.collectors.toctree.TocTreeCollector object at 0x104448b20>> for event 'doctree-read' threw an exception (exception: list index out of range)
make: *** [html] Error 2

• [x] The problem is at work

[ibrahimkelly]

Gonna take a look.

[kulothunganug]

Is the error appears when running make html inside docs directory?

[HeaTTheatR]

Is the error appears when running make html inside docs directory?

Updated the text of the issue

[p0lygun]

ok, i think i have a lead, working on this (gala_vs from discord)

[HeaTTheatR]

@p0lygun Thanks!

[BoolmanO]

im also trying to fix this

[HeaTTheatR]

im also trying to fix this

This is a issue already at work. Let's wait for the solution from @p0lygun

[T-Dynamos]

For info for the people who are working: After removing top doc string lines from swiper.py, fitimage.py and dropdownitem.py this error doesn't come. (make sure to do rm -rf sources/components/dropdownitem sources/components/fitimage sources/components/swiper/ before make html ie: remove those folders if they already exsits.). This may conclude there is some invisible error in docstrings of these files?

Click to view the patch

```patch diff '--color=auto' -uNr KivyMD-Latest_/kivymd/uix/dropdownitem/dropdownitem.py KivyMD-Latest/kivymd/uix/dropdownitem/dropdownitem.py --- KivyMD-Latest_/kivymd/uix/dropdownitem/dropdownitem.py 2024-01-10 21:48:48.602142210 +0530 +++ KivyMD-Latest/kivymd/uix/dropdownitem/dropdownitem.py 2024-01-10 21:41:32.298527916 +0530 @@ -1,80 +1,3 @@ -""" -Components/DropdownItem -======================= - -.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/dropdown-item.png - :align: center - -Usage ------ - -.. code-block:: python - - from kivy.lang import Builder - from kivymd.uix.menu import MDDropdownMenu - - from kivymd.app import MDApp - - KV = ''' - MDScreen - md_bg_color: self.theme_cls.backgroundColor - - MDDropDownItem: - pos_hint: {"center_x": .5, "center_y": .5} - on_release: app.open_menu(self) - - MDDropDownItemText: - id: drop_text - text: "Item" - ''' - - - class Example(MDApp): - def open_menu(self, item): - menu_items = [ - { - "text": f"{i}", - "on_release": lambda x=f"Item {i}": self.menu_callback(x), - } for i in range(5) - ] - MDDropdownMenu(caller=item, items=menu_items).open() - - def menu_callback(self, text_item): - self.root.ids.drop_text.text = text_item - - def build(self): - return Builder.load_string(KV) - - - Example().run() - -.. seealso:: - - `Work with the class MDDropdownMenu see here `_ - -API break -========= - -1.2.0 version -------------- - -.. code-block:: kv - - MDDropDownItem: - text: 'Item' - on_release: print(*args) - -2.0.0 version -------------- - -.. code-block:: kv - - MDDropDownItem: - on_release: print(*args) - - MDDropDownItemText: - text: "Item text" -""" __all__ = ("MDDropDownItem", "MDDropDownItemText") diff '--color=auto' -uNr KivyMD-Latest_/kivymd/uix/fitimage/fitimage.py KivyMD-Latest/kivymd/uix/fitimage/fitimage.py --- KivyMD-Latest_/kivymd/uix/fitimage/fitimage.py 2024-01-10 21:48:48.605475571 +0530 +++ KivyMD-Latest/kivymd/uix/fitimage/fitimage.py 2024-01-10 21:41:50.242013543 +0530 @@ -1,83 +1,3 @@ -""" -Components/FitImage -=================== - -Example -======= - -.. tabs:: - - .. tab:: Declarative KV styles - - .. code-block:: python - - from kivy.lang import Builder - - from kivymd.app import MDApp - - KV = ''' - MDScreen: - md_bg_color: self.theme_cls.backgroundColor - - MDBoxLayout: - radius: "36dp" - pos_hint: {"center_x": .5, "center_y": .5} - size_hint: .4, .8 - md_bg_color: self.theme_cls.onSurfaceVariantColor - - FitImage: - source: "image.png" - size_hint_y: .35 - pos_hint: {"top": 1} - radius: "36dp", "36dp", 0, 0 - ''' - - - class Example(MDApp): - def build(self): - return Builder.load_string(KV) - - - Example().run() - - - .. tab:: Declarative python styles - - .. code-block:: python - - from kivy.metrics import dp - - from kivymd.app import MDApp - from kivymd.uix.card import MDCard - from kivymd.uix.fitimage import FitImage - from kivymd.uix.screen import MDScreen - - - class Example(MDApp): - def build(self): - return ( - MDScreen( - MDBoxLayout( - FitImage( - source="image.png", - size_hint_y=0.35, - pos_hint={"top": 1}, - radius=(dp(36), dp(36), 0, 0), - ), - radius=dp(36), - md_bg_color=self.theme_cls.onSurfaceVariantColor, - pos_hint={"center_x": 0.5, "center_y": 0.5}, - size_hint=(0.4, 0.8), - ), - ) - ) - - - Example().run() - -.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/fitimage-round-corners.png - :align: center -""" __all__ = ("FitImage",) diff '--color=auto' -uNr KivyMD-Latest_/kivymd/uix/swiper/swiper.py KivyMD-Latest/kivymd/uix/swiper/swiper.py --- KivyMD-Latest_/kivymd/uix/swiper/swiper.py 2024-01-10 21:48:48.615475651 +0530 +++ KivyMD-Latest/kivymd/uix/swiper/swiper.py 2024-01-10 21:42:06.995488704 +0530 @@ -1,199 +1,3 @@ -""" -Components/Swiper -================= - -.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/mdswiper-preview.gif - :align: center - -Usage -===== - -.. code-block:: kv - - MDSwiper: - - MDSwiperItem: - - MDSwiperItem: - - MDSwiperItem: - -Example -======= - -.. code-block:: python - - from kivymd.app import MDApp - from kivy.lang.builder import Builder - - kv = ''' - - - FitImage: - source: "guitar.png" - radius: [20,] - - MDScreen: - - MDTopAppBar: - id: toolbar - title: "MDSwiper" - elevation: 4 - pos_hint: {"top": 1} - - MDSwiper: - size_hint_y: None - height: root.height - toolbar.height - dp(40) - y: root.height - self.height - toolbar.height - dp(20) - - MySwiper: - - MySwiper: - - MySwiper: - - MySwiper: - - MySwiper: - ''' - - - class Main(MDApp): - def build(self): - return Builder.load_string(kv) - - Main().run() - -.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/mdswiper-example.gif - :align: center - -.. warning:: - The width of :class:`MDSwiperItem` is adjusted automatically. Consider changing - that by :attr:`~MDSwiperItem.width_mult`. - -.. warning:: - The width of :class:`MDSwiper` is automatically adjusted according to the width of the window. - -.. rubric:: :class:`~MDSwiper` provides the following events for use: - -.. code-block:: python - - __events__ = ( - "on_swipe", - "on_pre_swipe", - "on_overswipe_right", - "on_overswipe_left", - "on_swipe_left", - "on_swipe_right" - ) - -.. code-block:: kv - - MDSwiper: - on_swipe: print("on_swipe") - on_pre_swipe: print("on_pre_swipe") - on_overswipe_right: print("on_overswipe_right") - on_overswipe_left: print("on_overswipe_left") - on_swipe_left: print("on_swipe_left") - on_swipe_right: print("on_swipe_right") - -Example -======= - -.. code-block:: python - - from kivy.lang.builder import Builder - - from kivymd.app import MDApp - - kv = ''' - - - - - - RelativeLayout: - - FitImage: - source: "guitar.png" - radius: [20,] - - MDBoxLayout: - adaptive_height: True - spacing: "12dp" - - MagicButton: - id: icon - icon: "weather-sunny" - user_font_size: "56sp" - opposite_colors: True - - MDLabel: - text: "MDLabel" - font_style: "H5" - size_hint_y: None - height: self.texture_size[1] - pos_hint: {"center_y": .5} - opposite_colors: True - - - MDScreen: - - MDTopAppBar: - id: toolbar - title: "MDSwiper" - elevation: 4 - pos_hint: {"top": 1} - - MDSwiper: - size_hint_y: None - height: root.height - toolbar.height - dp(40) - y: root.height - self.height - toolbar.height - dp(20) - on_swipe: self.get_current_item().ids.icon.shake() - - MySwiper: - - MySwiper: - - MySwiper: - - MySwiper: - - MySwiper: - ''' - - - class Main(MDApp): - def build(self): - return Builder.load_string(kv) - - - Main().run() - -.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/mdswiper-on-swipe.gif - :align: center - -How to automatically switch a SwiperItem? -========================================= - -Use method :attr:`~MDSwiper.set_current` which takes the index of :class:`MDSwiperItem` as argument. - -Example -======= - -.. code-block:: kv - - MDSwiper: - id: swiper - - MDSwiperItem: # First widget with index 0 - - MDSwiperItem: # Second widget with index 1 - - MDRaisedButton: - text: "Go to Second" - on_release: swiper.set_current(1) -""" __all__ = ("MDSwiperItem", "MDSwiper") ``` To apply run `patch --directory="kivymd dir" --strip=1 < "saved patch file here"`

But unfortunately then other error occurs in last writing output step.

@HeaTTheatR can you confirm the above results?

[HeaTTheatR]

@T-Dynamos No It doesn't work.

[HeaTTheatR]

@T-Dynamos

[HeaTTheatR]

@T-Dynamos The error is not with the documentation syntax...

[T-Dynamos]

html.zip

Faulty modules according to me:

components/refreshlayout/
components/dropdownitem/
components/fitimage/
components/swiper/

:)

[T-Dynamos]

Command to reproduce my build:

git clone https://github.com/kivymd/Kivymd --depth 1 --branch 2.0.0 KivyMD_test
cd KivyMD_test
rm -rf kivymd/uix/dropdownitem kivymd/uix/fitimage kivymd/uix/refreshlayout kivymd/uix/swiper
cd docs
make html

@HeaTTheatR can you now try to reproduce it?

[HeaTTheatR]

@T-Dynamos Yes, it works. But this does not fix the build process.

[HeaTTheatR]

@p0lygun Thanks, your PR corrects the documentation build! Can you log in to Open Collective and request a reward - https://opencollective.com/kivymd/expenses/new In the description of the reward, provide a link to this issue