On 09/06/2024 22.24, Nilson Silva wrote:
Hi Michael! Don't be surprised, but I always like to thank people who teach me things.
Hey Nilson, thank you for your nice email. I'm CC'ing my reply to the Debian Science mailing list so that we can have a public conversation.
Once again, I would like to thank you for updating a package that I am "_uploaders_": mapclassify. Between the updates, you did something that seemed new to me, that I didn't know about: the introduction of the intersphinx directory with objects: geopandas_objects.inv matplotlib_objects.inv networkx_objects.inv Where patches are configured, for local access. Of course I can use them. But are these files available on any server?
Yes, any Sphinx project will have these "objects.inv" files, see https://salsa.debian.org/science-team/mapclassify/-/blob/395ba6deb89bd925fc501faeadc5e41793542488/debian/rules#L22 for the rule I added to refresh them.
I'm thinking about presenting your updates for other packages. Could you give me a more detailed explanation of this situation or tell me where I can find more information?
Some notes on the intersphinx patch, https://salsa.debian.org/science-team/mapclassify/-/blob/395ba6deb89bd925fc501faeadc5e41793542488/debian/patches/intersphinx :
"geopandas": ("https://geopandas.org/en/latest/";, "../debian/intersphinx/geopandas_objects.inv"),
This will generate URLS starting with "https://geopandas.org/en/latest/"; using the map (inventory) of link targets that we downloaded from https://geopandas.org/en/stable/objects.inv ; no network access will occur because we provide a local file
"numpy": ("/usr/share/doc/python-numpy/html/", None),
Due to the "None", sphinx will append "objects.inv" to the base path to find the inventory file "/usr/share/doc/python-numpy/html/objects.inv" ; links will be made to the packaged docs starting with the path /usr/share/doc/python-numpy/html/ ; this only works if there is a Debian package providing those files. In this case that package is python-numpy-doc: https://packages.debian.org/sid/all/python-numpy-doc/filelist . For all Debian packages of software that uses Sphinx to manage their documentation, we would ideally package that documentation so other packaged software that use the intersphinx feature can link to the packaged version. (Not to mention, the user benefit of offline docs that match the installed version). For documentation that is not yet packaged (or might never be packaged), then I recommend creating the snapshots so that the web links still work.
By the way, there is an open bug on this subject: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1067014 May I close? Grateful!
Yes, that can be closed, thanks! -- Michael R. Crusoe
Attachment:
OpenPGP_signature.asc
Description: OpenPGP digital signature