Separate resources docs from other importlib docs

[jaraco]

BPO	46109
Nosy	@jaraco, @ericsnowcurrently
PRs	bpo-46109: Separate out files relating to importlib.resources #30160

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/jaraco'
closed_at = <Date 2021-12-31.13:40:47.128>
created_at = <Date 2021-12-17.02:10:06.582>
labels = ['3.11', 'docs']
title = 'Separate resources docs from other importlib docs'
updated_at = <Date 2021-12-31.13:40:47.127>
user = 'https://github.com/jaraco'

bugs.python.org fields:

activity = <Date 2021-12-31.13:40:47.127>
actor = 'jaraco'
assignee = 'jaraco'
closed = True
closed_date = <Date 2021-12-31.13:40:47.128>
closer = 'jaraco'
components = ['Documentation']
creation = <Date 2021-12-17.02:10:06.582>
creator = 'jaraco'
dependencies = []
files = []
hgrepos = []
issue_num = 46109
keywords = ['patch']
message_count = 11.0
messages = ['408749', '408798', '408799', '408814', '408816', '408913', '408914', '408915', '408918', '409234', '409399']
nosy_count = 2.0
nosy_names = ['jaraco', 'eric.snow']
pr_nums = ['30160']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue46109'
versions = ['Python 3.11']

[jaraco]

The importlib documentation is fairly long and covers a number of topics. Furthermore, the importlib.metadata is separately documented and presents a good example of breaking out major aspects. Let's do the same with .abc and .resources.

[ericsnowcurrently]

+1 to splitting out the importlib.resources docs

I'm mostly +1 for splitting out the others (.abc, .machinery, .util) too, not just .abc.

Regardless, a ToC at the top of the main page which identifies the submodules (and provides a brief summary for each) would be extra helpful. I suppose that could be helpful regardless of whether or not we move submodule docs out.

[ericsnowcurrently]

FWIW, one benefit to having everything in one doc (instead of one doc per submodule) is that it's a little easier to see the bigger picture. This is particularly important for folks interested in customizing the import system (rather than just interacting with it).

However, they would probably be better served by an explicit section on how to customize the import system. The language reference provides the info but its focus is to specify rather than to guide. So it may make sense to have a dedicated section to at least cover the supported customization approaches (at a high level).

This would definitely be covered by a separate issue but it makes less sense if we don't move the submodules to their own docs.

[jaraco]

My main motivation for moving .abc was because it contains classes exclusively relevant to .resources (those also present in importlib_resources.abc. I want to explore moving those classes to the resources documentation so they're available together and maintained independently.

Other classes in .abc are relevant to the import system more generally, so maybe should stay in the main docs.

[jaraco]

I wonder if maybe it's more important to address bpo-46118 first.

[jaraco]

The reason I wanted to consider bpo-46118 first was because I wanted to explore whether the ABCs from importlib_resources.abc should be documented as importlib.resources.abc or importlib.abc (as they are now).

After filing the issue and exploring the concerns (namely, should users be directed away from importlib.abc for these classes), I'm uncertain whether it's worth the effort to make that transition, and certainly not in haste, so this effort can proceed to document the status quo (ABCs presented primarily in importlib.abc).

[jaraco]

a ToC at the top of the main page which identifies the submodules (and provides a brief summary for each) would be extra helpful.

I've added this in the latest commit (1adefaf).

[jaraco]

As I'm exploring this issue, I notice that currently, the docs refer to :class:`importlib.resources.abc.Traversable` (even though that doesn't currently exist) (https://github.com/python/cpython/blame/main/Doc/library/importlib.rst#L948).

[jaraco]

I realize, I can limit the scope of this issue to address 'resources' alone, leaving ABCs where they are except for resource-related ones, allowing us to defer a larger refactoring to a separate issue/effort.

[ericsnowcurrently]

+1