~Impossible to write a general algorithm to properly construct it for nonstandard docs layouts.
ALTHOUGH -- if a user has pasted a link to the actual docset as the input argument for suggest, then we can pretty strongly infer that that is a valid page in the docset. We can then search the uris in the inventory for one that matches the tail of the link passed in by the user. If the head of that link is the same as the location of the found objects.inv, then the ({objects_url}, None) syntax will work. If not, then the ({docs_base_url}, {objects_url}) syntax will be needed.
OTOH, we can't be sure that all input URLs will be pasted from a page in the docs, so a failure to match on this rubric doesn't mean that the root of the objects.inv URL isn't the correct docset root for the mapping...just that we can't be sure.
If the tail of the objects.inv URL is not/objects.inv, then we can be 100% sure that the mapping will not be (..., None), but instead (some_url, objectsinv_url). The only way to determine some_url is if the user also provides a URL to an object in the docset, and then we can extract the base from that using the Inventory objects, presuming one matches. This might mean that it would be best to expose that base-finding function as public...
Implement as helper function in the API, exploited by the CLI? (Yes. Standalone in a new module. DO NOT cross-implement as a method on Inventory, would lead to an import cycle.) Should just need objects_url and docs_link_url? (Yes, plus the retrieved Inventory.)
TODO:
[x] Convert objects.inv base extractor to public function
[x] Compose docstrings for functions:
[x] objects.inv base extractor
[x] mapping inferrer
[x] Implement CLI use of the new functions
Make sure the language is suitably tentative ("The following mapping SHOULD work for ...", "The following mapping MAY work for ...", "No candidate mapping for ... could be determined.")
~Add API documentation page~ Leaving the whole new module private for now (at sphobjinv._intersphinx)
~Add HOWTO docs page for finding mappings through API~ (Now, no public API)
[x] Fix extract_objectsinv_url_base() (can't just do a blind rpartition... have to do the rpartition and then check if the [0] is empty, and handle accordingly)
Django inv is the main driver here
[x] Add tests on some links to the sphobjinv RtD docset
[x] Refactor to remove _intersphinx.py
[x] Add tag to commit before remove for later access if needed
[x] Fill out coverage; add pragmas as needed
[x] Check if need to update any usage examples, or if they're all using .. programoutput:: and will auto-update
~Trivial for standard docs layout
~Impossible to write a general algorithm to properly construct it for nonstandard docs layouts.
ALTHOUGH -- if a user has pasted a link to the actual docset as the input argument for
suggest, then we can pretty strongly infer that that is a valid page in the docset. We can then search theuris in the inventory for one that matches the tail of the link passed in by the user. If the head of that link is the same as the location of the foundobjects.inv, then the({objects_url}, None)syntax will work. If not, then the({docs_base_url}, {objects_url})syntax will be needed.OTOH, we can't be sure that all input URLs will be pasted from a page in the docs, so a failure to match on this rubric doesn't mean that the root of the
objects.invURL isn't the correct docset root for the mapping...just that we can't be sure.If the tail of the
objects.invURL is not/objects.inv, then we can be 100% sure that the mapping will not be(..., None), but instead(some_url, objectsinv_url). The only way to determinesome_urlis if the user also provides a URL to an object in the docset, and then we can extract the base from that using theInventoryobjects, presuming one matches. This might mean that it would be best to expose that base-finding function as public...Implement as helper function in the API, exploited by the CLI? (Yes. Standalone in a new module. DO NOT cross-implement as a method on
Inventory, would lead to an import cycle.) Should just needobjects_urlanddocs_link_url? (Yes, plus the retrievedInventory.)TODO:
sphobjinv._intersphinx)extract_objectsinv_url_base()(can't just do a blindrpartition... have to do therpartitionand then check if the[0]is empty, and handle accordingly)_intersphinx.py.. programoutput::and will auto-update