search

kedro-org / kedro

Kedro is a toolbox for production-ready data science. It uses software engineering best practices to help you create data engineering and data science pipelines that are reproducible, maintainable, and modular.
https://kedro.org
Apache License 2.0
9.9k stars 899 forks source link

Consider more modern theme for docs #2394

Closed astrojuanlu closed 10 months ago

astrojuanlu commented 1 year ago

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)

image

PyData Sphinx Theme

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

image

Lutra

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

image

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:

image

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 https://github.com/readthedocs/sphinx_rtd_theme/issues/295, ahem 7 years ago).

(Potentially overlaps or conflicts with kedro-org/kedro#2072)

yetudada commented 1 year ago

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 commented 1 year ago

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 kedro-org/kedro#2072.

datajoely commented 1 year ago

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 commented 1 year ago

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

astrojuanlu commented 1 year ago

OMG https://sphinxawesome.xyz/

datajoely commented 1 year ago

OMG https://sphinxawesome.xyz/

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

astrojuanlu commented 1 year ago

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 commented 10 months ago

@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 https://github.com/kedro-org/kedro-sphinx-theme/issues/5

stichbury commented 10 months ago

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

astrojuanlu commented 10 months ago

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