Consider more modern theme for docs

[astrojuanlu]

I find navigating the Kedro docs quite daunting, and I don't think trimming them down (as @stichbury and I are trying to do) will significantly improve the situation. For example, when landing to a random page, it's difficult to locate the subsections on the left menu (I usually Ctrl/Cmd+F or just scroll up and down until I find it).

As an idea, we could use the right hand side of the page to place an extra navigation menu, which is what many modern themes are doing. See for example:

Furo

https://pradyunsg.me/furo/customisation/ (left + right navigation)

PyData Sphinx Theme

https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/layout.html (left + right + top navigation)

Lutra

https://pradyunsg.me/lutra/porting/organise-configuration/ (left + right + top navigation)

---

All these screenshots were taken from my laptop screen (no external monitor) at the default Zoom level. This is how Kedro landing looks like as a comparison:

We are using a highly customized version of html_theme = "sphinx_rtd_theme", which is quite responsive on mobile and was much better than the average Sphinx theme when it was created. However, it is known to waste lots of horizontal space and we kind of inherited that (see this issue from 2016 readthedocs/sphinx_rtd_theme#295, ahem 7 years ago).

(Potentially overlaps or conflicts with #2072)

[yetudada]

Ah, this ties in with the branding workstream. We're going to do an overhaul of the docs as one of the outputs from that workstream.

[stichbury]

Came here to say this. I agree but (a) we need to decide a docs toolchain & host and (b) do the rebranding. As a more temporary step to help reading, any extensions that help (like a floating table of contents on the RHS) would be worth considering, but otherwise let's prioritise #2072.

[datajoely]

I'd also validate how much of a pain migrating to MkDocs would be, here's a lovely example:
https://textual.textualize.io/api/app/

[stichbury]

We are going to pick this up in the sprint w/c 17th April

[astrojuanlu]

OMG https://sphinxawesome.xyz/

[datajoely]

OMG https://sphinxawesome.xyz/

Wow! They managed to get search to be useful too, that's all I really really like about mkdocs

[astrojuanlu]

No wonder - the person who created the theme works at Algolia 😄 https://github.com/kai687/sphinxawesome-theme/blob/81277a4/src/sphinxawesome_theme/docsearch.py

[astrojuanlu]

@amandakys was already working on a redesign of the docs so this is still pretty much desired. It will not only be a theme change though, but will also touch the information architecture and other things.

Let's continue the discussion in #4257

[stichbury]

Shall we close this one then? I'll leave you to decide @astrojuanlu as the creator.

[astrojuanlu]

Most of the info is on the other issue anyway, so I'll close this one.