Documentation renders poorly on small screens.

[Julian-O]

trafficstars

Software Versions

• Kivy: 2.2.1

The documentation renders poorly when read on small screens.

Examples:

Here is a snippet from the events documentation, as rendered in Chrome on a Windows desktop:

Here is the same snippet on a Samsung phone, with the Samsung browser:

The poor indenting changes the meaning of the code.

Here is another example, taken from Widget documentation:

Describe the bug

Consider replacing the theme with one that works on small screens.

[misl6]

I'm working to have Kivy docs work seamlessly on furo theme (but I'm open to alternatives).

[FilipeMarch]

I recommend using mkdocs + mkdocstrings for replacing sphinx

[Julian-O]

@FilipeMarch: That would require a substantial effort to move all the documentation into MarkDown. Do you have more than a recommendation to justify this effort? Are you willing to do that work?

[rnixx]

This is not an issue about sphinx or restructured text, but the theme used for generating the docs.

I'd suggest to pick one from https://sphinx-themes.org/ and make kivy related adoptions to it if desired.

Edit Updated URL to themes

[baseplate-admin]

I'm working to have Kivy docs work seamlessly on furo theme (but I'm open to alternatives).

To be honest furo is a good theme but i have some gripes against it. Reason:

• Too many projects use furo ( leads to repetitiveness )

So what do i suggest :

• shibuya ( qtile folks seem to like shibuya )

[Julian-O]

Too many projects use furo

I've haven't carefully reviewed furo, but this is the strongest argument I have heard for it! ;-) Bugs are probably already ironed out, and if they are not, there are more eyeballs looking for them.

If we were trying to get people to pick our product up off the shelf by having a distinctive cover, I would totally get your point, but having our documentation look exactly like everyone else's, and being easier to navigate through familiarity seems like a plus to me.

[baseplate-admin]

If we were trying to get people to pick our product up off the shelf by having a distinctive cover, I would totally get your point, but having our documentation look exactly like everyone else's, and being easier to navigate through familiarity seems like a plus to me.

Well both follow same structure, except some color scheme change

---

Well not that i am against furo, i am just saying to approach this with an open mind ;)

[FilipeMarch]

Well if you guys like sphinx, why not using sphinx-immaterial? It has the best of both worlds! mkdocs is super pretty, easy to use, responsive, well funded and frequently updated.

I would love to edit a lot of Kivy's documentation, put more examples using each property of the widgets, add images, videos, etc. But currently the general theme is not super pretty and there's a lack of easily customizable components that mkdocs offers.

I'm doing these tutorials on Kivy School but I would prefer to make PRs directly to Kivy's documentation.

https://github.com/kivy/kivy/assets/23220309/96ec1b31-fd09-4894-8cff-e20cffb9c470

It is super easy to use mkdocs, anyone can learn it because it's basically markdown.

I can make at least my own commitment: if you guys add mkdocs support on Kivy docs I will edit at least 12 different pages in a 2-month period. I'm sure I can find more people interested in doing the same.

[Julian-O]

Well if you guys like sphinx, why not using sphinx-immaterial?

My concern with your suggestion isn't how Markdown looks. It doesn't need to "look like Sphinx".

My concern is a Sphinx theme change is half a dozen lines per repo. A change to Markdown means:

• Identifying all the plugins we need to match the Sphinx features we use (e.g. link-checking, cross-referencing between pages, tables of contexts, generating PDF, cross-referencing other versions available, search tools)
• Replacing the build tools.
• Updating all the CI actions across all the repos.
• Updating how the Kivy.org pages are deployed.

and then, most importantly, the mundane task of editing every single page, and editing every link, warning, cross-reference, subheading, ToC, etc. (Hopefully there are tools to automate some of this.)

As someone far more comfortable with markdown than RST, I would welcome this, but it is a lot of work.

[I am currently helping to move the project FAQs from RST to MD, because it is important that experts feel comfortable editing them quickly.]

[rnixx]

Actually, sphinx can also be used with markdown -> https://myst-parser.readthedocs.io/en/latest/index.html I already used it and it works pretty well. Using myst has also the advantage that transition can happen step by step, it's totally fine to mix up markdown and restructured text files.

Anyway, i really see no benefit in changing all the documentation to another format just for the sake of it. If someone wants to take all the burden that comes along with it then go ahead, but IMHO this is just a waste of time.