Duplication and inconsistencies exist across different documentation subprojects

[astrojuanlu]

Description

We are starting to have lots of duplicated work across our 3 subprojects: core, viz, and datasets. This includes

• CSS files (now in an external storage for reuse, see Move Kedro documentation CSS to package allow sharing across subprojects #3016)
• Template files
• JavaScript code that enables Heap Analytics
• JavaScript code that enables search-as-you-type
• JavaScript code that enables Cmd+K as a keyboard shortcut for search
• Sphinx dependencies and plugins

Context

This situation is starting to pose some problems. For example, now making small adjustments to the CSS requires access to an object storage and they are not under version control. In addition, we now have inconsistent documentation dependencies across repositories, and maintaining them in sync is a burden.

We'd need to tackle this before #4257.

Possible Implementation

Create a custom Sphinx theme, so we can do

# pyproject.toml
[project.optional-dependencies]
docs = [
    "kedro-sphinx-theme==0.1.0",
]

And that already contains everything we need.

Possible Alternatives

❓

[stichbury]

Agreed. However, does it make sense to wait and make the theme based on docs redesign or can we make a theme now for what we have and then upgrade it? And, also, who makes this theme -- is it front end work for the Viz developers?

[astrojuanlu]

For clarity, we wouldn't be crafting anything new: just packing our existing sphinx-rtd-theme modifications into a pip-installable package. So in principle this is "backend" work only.

Then that pip-installable package gives us the foundation to make any actual modifications to the theme itself.

[astrojuanlu]

More inconsistencies across projects: kedro-org/kedro-viz#1734

[tynandebold]

CSS files (now in an external storage for reuse, see #3016)

I opened a PR in the brand identity repo to solve this first point: kedro-org/kedro-brand-identity#7

[astrojuanlu]

Okay, it's happening https://github.com/kedro-org/kedro-sphinx-theme

[astrojuanlu]

Adding this to our backlog so we can prioritize accordingly.

[astrojuanlu]

Waiting for reviews on #3675

[astrojuanlu]

• Kedro Use kedro-sphinx-theme #3675
• kedro-datasets Use kedro-sphinx-theme in kedro-datasets kedro-plugins#662
• kedro-viz Enhance Kedro-viz doc styling by using kedro-sphinx-theme kedro-viz#1882

[astrojuanlu]

This has now been addressed across all 3 subprojects. Closing.

[astrojuanlu]

Follow-up #3864