Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Separate resources docs from other importlib docs #90267

Closed
jaraco opened this issue Dec 17, 2021 · 11 comments
Closed

Separate resources docs from other importlib docs #90267

jaraco opened this issue Dec 17, 2021 · 11 comments
Assignees
Labels
3.11 bug and security fixes docs Documentation in the Doc dir

Comments

@jaraco
Copy link
Member

jaraco commented Dec 17, 2021

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
    Copy link
    Member Author

    jaraco commented Dec 17, 2021

    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.

    @jaraco jaraco added the 3.11 bug and security fixes label Dec 17, 2021
    @jaraco jaraco self-assigned this Dec 17, 2021
    @jaraco jaraco added the docs Documentation in the Doc dir label Dec 17, 2021
    @ericsnowcurrently
    Copy link
    Member

    +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
    Copy link
    Member

    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
    Copy link
    Member Author

    jaraco commented Dec 17, 2021

    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
    Copy link
    Member Author

    jaraco commented Dec 17, 2021

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

    @jaraco
    Copy link
    Member Author

    jaraco commented Dec 19, 2021

    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
    Copy link
    Member Author

    jaraco commented Dec 19, 2021

    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
    Copy link
    Member Author

    jaraco commented Dec 19, 2021

    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
    Copy link
    Member Author

    jaraco commented Dec 19, 2021

    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.

    @jaraco jaraco changed the title Separate resources and abc docs from other importlib docs Separate resources docs from other importlib docs Dec 19, 2021
    @jaraco jaraco changed the title Separate resources and abc docs from other importlib docs Separate resources docs from other importlib docs Dec 19, 2021
    @ericsnowcurrently
    Copy link
    Member

    +1

    @jaraco
    Copy link
    Member Author

    jaraco commented Dec 31, 2021

    New changeset 99945c6 by Jason R. Coombs in branch 'main':
    bpo-46109: Separate out files relating to importlib.resources (GH-30160)
    99945c6

    @jaraco jaraco closed this as completed Dec 31, 2021
    @jaraco jaraco closed this as completed Dec 31, 2021
    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    3.11 bug and security fixes docs Documentation in the Doc dir
    Projects
    None yet
    Development

    No branches or pull requests

    2 participants