Deprecate kedro.extras.datasets and add top-level docs for kedro_datasets

[astrojuanlu]

Description

Fix gh-1501.

• Add admonition to kedro/extras/datasets/README.md, visible on GitHub (link):

• Add admonotion to kedro/extras/datasets/__init__.py, visible in the docs:

• Emit a DeprecationWarning whenever kedro.extras.datasets is imported:

• Hide kedro.extras.datasets from the kedro.extras toctree (not from the navigation bar because that's not possible - an alternative is to declare it as :orphan:)

• And... 🥁 added top-level documentation for kedro_datasets + replace misleading kedro.datasets references that didn't exist + simplify the documentation builds by removing the special script!

Development notes

The special handling of kedro_datasets was introduced in gh-2006.

Checklist

• Read the contributing guidelines
• Opened this PR as a 'Draft Pull Request' if it is work-in-progress
• Updated the documentation to reflect the code changes
• Added a description of this change in the RELEASE.md file
• Added tests to cover my changes

[astrojuanlu]

Rendered docs 🤖

• https://kedro--2546.org.readthedocs.build/en/2546/kedro.extras.datasets.html
• https://kedro--2546.org.readthedocs.build/en/2546/kedro_datasets.html

[merelcht]

How do the kedro-datasets docs get build without the script? They're not part of the repo so how can sphinx build them?

[astrojuanlu]

@merelcht here's the magic. autodoc and sphinx.ext.autosummary only need to be able to import the objects, they don't even have to be downloaded physically!

[merelcht]

So you need to have kedro-datasets installed? And what if you have an older version, would it then build old docs?

[astrojuanlu]

That's correct, it will load whatever version is installed. Since the docs extras-requires is getting installed, kedro-datasets and all its dependencies were already there:

kedro/Makefile

Lines 36 to 37 in a95ce7a

	build-docs:
	pip install -e ".[docs]"

kedro/setup.py

Line 109 in a95ce7a

"kedro-datasets[api,biosequence,dask,geopandas,matplotlib,holoviews,networkx,pandas,pillow,polars,video,plotly,redis,spark,svmlight,yaml]==1.1.1",

[merelcht]

Alright, so I guess in that case we need to make sure to bump the pin here whenever we do a kedro-datasets release to make sure docs are the most recent.

[merelcht]

I've added checking to bump the kedro-datasets doc requirements as a step in the release notes.

[stichbury]

Looks great to me! Thank you 🌟

[merelcht]

Let's add this to the release notes as well so we remember when we added the deprecation warnings.

[astrojuanlu]

I see you went ahead and added it, thanks @merelcht 🙏🏽

[zedrdave]

Sorry if I missed something, but shouldn't _DEFAULT_PACKAGES also be modified from:
_DEFAULT_PACKAGES = ["kedro.io.", "kedro_datasets.", "kedro.extras.datasets.", ""]

to:
_DEFAULT_PACKAGES = ["kedro.io.", "kedro_datasets.", "", "kedro.extras.datasets."]

Currently, the DeprecationWarning will be fired whenever using a custom class string.

[astrojuanlu]

Hey @zedrdave , possibly - could you open a new issue so it has more visibility?