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 https://github.com/kedro-org/kedro/issues/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 https://github.com/kedro-org/kedro-viz/issues/1474.

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: https://github.com/kedro-org/kedro-viz/issues/1734

[tynandebold]

CSS files (now in an external storage for reuse, see https://github.com/kedro-org/kedro/issues/3016)

I opened a PR in the brand identity repo to solve this first point: https://github.com/kedro-org/kedro-brand-identity/pull/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 https://github.com/kedro-org/kedro/pull/3675

[astrojuanlu]

• [x] Kedro https://github.com/kedro-org/kedro/pull/3675
• [x] kedro-datasets https://github.com/kedro-org/kedro-plugins/issues/662
• [x] kedro-viz https://github.com/kedro-org/kedro-viz/issues/1882

[astrojuanlu]

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

[astrojuanlu]

Follow-up kedro-org/kedro#3864