Improving the documentation #240

Activity

1. FFY00 commented on Oct 22, 2021

   

   FFY00

   on Oct 22, 2021

   Member

   More actions

   Explain what is meant for ResourceReader to be "superseded by" TraversableResources.

   Perhaps it could be made clearer, but it is explained. TraversableResources takes your files() and implements ResourceReader. I am not sure how we would reword it, though.
   Defining ResourceReader directly is superseded by using TraversableResources instead and just defining files(). You still get the ResourceReader implementation for compatibility, but you make available a files() API, which is a much better abstraction than what we had before.

   Document the TraversableResources interface (its files method).

   Yup. This was on my TODO list, I meant to do it earlier this week but it feel down.

   python/cpython#29173

   Explain that TraversableResources is a concrete implementation of ResourceReader, where only files is abstract, not an abstract base class as stated.

   This goes into the first point, we could update the description to be clearer.

   Under the resources heading, demarcate the old (soon to be deprecated) API from the new API and discourage usage of the old API.

   Yup. I think the docs could use a touch-up. I was meaning to add an API reference section, which would clearly mark the legacy API as deprecated or slated for deprecation, whatever we end up doing. Ideally, the rest of the documentation would only reference this API in the migration sections. I am gonna wait for resolution on #80 to do this.

   Document the Traversable interface. This is a particularly pernicious one because without documentation users do not know which attributes of a pathlib.Path object, which is what would be typically returned from files(), are safe to use, and which methods are safe to call, with which arguments.

   python/cpython#29039
   https://docs.python.org/3.11/library/importlib.html#importlib.abc.Traversable
2. layday commented on Oct 22, 2021

   

   layday

   on Oct 22, 2021

   Author

   More actions

   python/cpython#29039

   Not sure I understand why that can't be backported to 3.9 and 3.10 if the docs are maintained independently?
3. layday commented on Oct 22, 2021

   

   layday

   on Oct 22, 2021

   Author

   More actions

   python/cpython#29039 has

       .. abstractmethod:: name()
   
          The base name of this object without any parent references.
   

   but name is a property there.
4. FFY00 commented on Oct 22, 2021

   

   FFY00

   on Oct 22, 2021

   Member

   More actions

   Agh!
5. jaraco commented on Oct 31, 2021

   

   jaraco

   on Oct 31, 2021

   Member

   More actions

   I am gonna wait for resolution on #80 to do this.

   I'd also wait on a call for python/cpython#29036 as that PR is the one that marks the functions as deprecated.
6. jaraco commented on Oct 31, 2021

   

   jaraco

   on Oct 31, 2021

   Member

   More actions

   I realize it's a little awkward having issues in this repo and also bpo, especially for importlib.resources, whose code lives primarily here but whose docs are exclusively in CPython but where there's a separate set of docs for this project. For the future, please consider filing docs bugs for importlib.resources in bpo.
7. jaraco

   added

   help wantedExtra attention is neededExtra attention is needed

   on Mar 26, 2022
8. jaraco commented on Jul 7, 2023

   

   jaraco

   on Jul 7, 2023

   Member

   More actions

   Since some work has been done and this issue seems to be languishing, I'm going to go ahead and close it. That said, I'd welcome anyone to re-invigorate the conversation or provide PRs to improve the situation.
9. jaraco

   closed this as completedon Jul 7, 2023