Move Kedro documentation CSS to package allow sharing across subprojects #3016

stichbury · 2023-08-18T09:12:12Z

Description

Following on from parent task #2600, there is one subtask that we need to do to fix the styling so any new subprojects for Viz, Datasets, Starters etc use exactly the same theme as the Kedro docs.

~~I'm not sure what is involved with this (I naively thought we could just copy the CSS around but I guess that's not exactly maintainable).~~ Edit: Now have a plan.

Please can I add to your queue @tynandebold for consideration & prioritisation.

stichbury · 2023-09-04T10:31:39Z

@tynandebold So this is probably a question of setting up a separate package for the docs theming folder that Kedro framework currently uses, so that when we put out other documentation subprojects for datasets, viz and starters, they can draw on the same by adding that package as a dependency.

The theme will initially be as we are using currently, with later updates for #4257. So, in theory, this ticket could enter any sprint that you are able to pick it up.

@astrojuanlu and I have briefly discussed but happy to talk more about practicalities when you have an engineer able to pick it up.

astrojuanlu · 2023-09-04T10:39:01Z

Exactly, the idea is to distribute the theme as pip install kedro-sphix-theme (or whatever other name) so it can be reused by the different repositories. I don't think there are many good docs on how to do such a thing, but we would be looking at doing what other themes are already doing, for example the one we derive from https://github.com/readthedocs/sphinx_rtd_theme/ or more modern ones like https://github.com/pradyunsg/furo/, which uses its own build backend https://sphinx-theme-builder.readthedocs.io/

tynandebold · 2023-09-07T14:44:57Z

Does it need to be pip installable? Could we instead host these two files in a centralized place and then use those URLs to reference the CSS via RTD?

Prerequisite for this is that we're able to add a custom <link> tag in the <head> section of a RTD project. I haven't looked into if this is possible.

stichbury · 2023-09-07T14:57:50Z

Does it need to be pip installable? Could we instead host these two files in a centralized place and then use those URLs to reference the CSS via RTD?

Prerequisite for this is that we're able to add a custom <link> tag in the <head> section of a RTD project. I haven't looked into if this is possible.

I think it's OK to use a link, from looking at this: https://docs.readthedocs.io/en/stable/guides/adding-custom-css.html

What you are suggesting is a "fully qualified path", right?

tynandebold · 2023-09-07T15:14:59Z

Yes indeed! Then I think we're in business and need not create a new Python package. We can dump these files on S3 or maybe even GitHub pages, adding them to a new repo in our organization.

Haven't thought it through too far other than to say this sounds like a wiser option.

astrojuanlu · 2023-09-09T12:45:03Z

Notice that it's not only CSS files we'd like to distribute: we're starting to have duplication in conf.py. Compare

kedro/docs/source/conf.py

Line 345 in e949c6c

def autolink_replacements(what: str) -> list[tuple[str, str, str]]:

with

https://github.com/kedro-org/kedro-plugins/blob/7d092dbdb9344af58435ed6a696331ecb80ae553/kedro-datasets/docs/source/conf.py#L240

The more Sphinx projects we add (and soon we'll need kedro-viz and others), the more stuff we need to copy-paste to conf.py that could be distributed as functions.

In addition, if we ever want to change the theme base from sphinx-rtd-theme to something else (which we absolutely want, see #4257) we'd need to again change the html_theme value in conf.py as well as the dependencies in every single package, which will become tedious soon.

As a result I'm all in favour of creating a new Python package.

tynandebold · 2023-09-11T08:55:40Z

I didn't notice that, thank you for pointing that out.

Since it's more than only CSS a new Python package seems best, as JuanLu said.

I know much less about that, though am still happy to help with the styling part.

astrojuanlu · 2023-09-11T16:29:34Z

Asked on pradyunsg/sphinx-theme-builder#45 and the Write the Docs community just to make sure I'm not spitting nonsense here.

stichbury · 2023-09-13T09:08:59Z

Hmm, I'm still not convinced though. Is the complexity of adding another package for reuse really worth the occasional conf.py edit when we aren't likely to be changing theme that often (I hope!). It also means each project is then bound to share a conf.py and this may not be ideal in some cases (e.g. link checker exclusions, extensions).

I'm not sure, but I still like the idea of keeping things simple, and not getting into reuse just because "we can" 🤷

astrojuanlu · 2023-09-13T15:51:22Z

To clarify, projects would not share a conf.py (I don't think that's possible) but could optionally load the modifications we make on demand.

Regardless, I don't want to become the bottleneck of this 😄 so if this is on the critical path towards #2600, then I'm okay with uploading the CSS assets somewhere and using those directly for now.

stichbury · 2023-09-13T16:40:20Z

Oh OK, that sounds better, but still a bit complicated for my poor 🧠 to compute. Let's just go with basic CSS as per @tynandebold's original suggestion on S3 or similar. Makes it simple and when/if we later need to dig ourselves out of the technical debt I'm dumping us in, I promise to be humble 😊

stichbury · 2023-10-19T10:36:08Z

Now at https://kedro-shared-files.s3.eu-west-2.amazonaws.com/theme-overrides.css

tynandebold · 2023-10-19T10:44:34Z

I've uploaded both theme files now:

cc @vladimir-mck

stichbury · 2023-10-19T12:59:09Z

We can close this as done now. The CSS is used in the Viz docs project and I will make a branch on develop for the same.

stichbury added the Issue: Feature Request New feature or improvement to existing feature label Aug 18, 2023

stichbury mentioned this issue Aug 18, 2023

Parent task: Set up subprojects for Kedro-Viz and kedro-datasets docs #2600

Closed

stichbury transferred this issue from kedro-org/kedro Aug 21, 2023

stichbury changed the title ~~Restyle Kedro subproject documentation~~ Move Kedro documentation CSS to package allow sharing across subprojects Sep 4, 2023

stichbury transferred this issue from kedro-org/kedro-viz Sep 7, 2023

stichbury added this to the Documentation subprojects milestone Sep 7, 2023

astrojuanlu mentioned this issue Oct 11, 2023

MVP implementation of meganav navigation between documentation subprojects #3024

Closed

tynandebold added Component: Documentation 📄 Issue/PR for markdown and API documentation and removed Issue: Feature Request New feature or improvement to existing feature labels Oct 16, 2023

tynandebold self-assigned this Oct 16, 2023

tynandebold moved this from Todo to In Progress in Kedro-Viz Oct 16, 2023

stichbury mentioned this issue Oct 18, 2023

Create docs project for Kedro-Viz kedro-org/kedro-viz#1586

Merged

5 tasks

stichbury closed this as completed Oct 19, 2023

github-project-automation bot moved this from In Progress to Done in Kedro-Viz Oct 19, 2023

astrojuanlu mentioned this issue Jan 16, 2024

Bump sphinx-rtd-theme from 1.2.0 to 2.0.0 #3511

Merged

astrojuanlu mentioned this issue Feb 1, 2024

Duplication and inconsistencies exist across different documentation subprojects #3586

Closed

astrojuanlu mentioned this issue May 13, 2024

Backfill some old documentation versions with static assets #3864

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Move Kedro documentation CSS to package allow sharing across subprojects #3016

Move Kedro documentation CSS to package allow sharing across subprojects #3016

stichbury commented Aug 18, 2023 •

edited

Loading

stichbury commented Sep 4, 2023

astrojuanlu commented Sep 4, 2023

tynandebold commented Sep 7, 2023

stichbury commented Sep 7, 2023

tynandebold commented Sep 7, 2023

astrojuanlu commented Sep 9, 2023

tynandebold commented Sep 11, 2023

astrojuanlu commented Sep 11, 2023

stichbury commented Sep 13, 2023 •

edited

Loading

astrojuanlu commented Sep 13, 2023

stichbury commented Sep 13, 2023

stichbury commented Oct 19, 2023

tynandebold commented Oct 19, 2023 •

edited

Loading

stichbury commented Oct 19, 2023

Move Kedro documentation CSS to package allow sharing across subprojects #3016

Move Kedro documentation CSS to package allow sharing across subprojects #3016

Comments

stichbury commented Aug 18, 2023 • edited Loading

Description

stichbury commented Sep 4, 2023

astrojuanlu commented Sep 4, 2023

tynandebold commented Sep 7, 2023

stichbury commented Sep 7, 2023

tynandebold commented Sep 7, 2023

astrojuanlu commented Sep 9, 2023

tynandebold commented Sep 11, 2023

astrojuanlu commented Sep 11, 2023

stichbury commented Sep 13, 2023 • edited Loading

astrojuanlu commented Sep 13, 2023

stichbury commented Sep 13, 2023

stichbury commented Oct 19, 2023

tynandebold commented Oct 19, 2023 • edited Loading

stichbury commented Oct 19, 2023

stichbury commented Aug 18, 2023 •

edited

Loading

stichbury commented Sep 13, 2023 •

edited

Loading

tynandebold commented Oct 19, 2023 •

edited

Loading