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.51k stars 877 forks source link

Documentation subproject cross-referencing needs to be more sophisticated #3289

Open stichbury opened 8 months ago

stichbury commented 8 months ago

Description

At present, it's not possible to cross reference between subprojects if you need to include a permalink to a subhead.

So it's fine to link to a page:

By convention, a {doc}`pipeline can be defined as having different layers<kedro:resources/glossary>`. 

But not to a header on a page.

By convention, a {doc}`pipeline can be defined as having different layers<kedro:resources/glossary#data-layers>`. 

@astrojuanlu has diagnosed this as resulting from the fact there's no explicit label defined for a section, so Sphinx didn't generate a std:label anchor to it and what you're trying to do won't work.

He says that the way to fix that would be to change the Kedro docs themselves by either:

For now, I'm retaining the hard-coded link old-school style but this should be fixed in due course.

astrojuanlu commented 3 months ago

This is still a priority, but I'm releasing @stichbury from doing it