Intersphinx objects.inv borked

[cstarkjp]

In 1.6.1, the following intersphinx:

'sympy': ('https://docs.sympy.org/latest', None)

links to

https://docs.sympy.org/1.6.1/modules/matrices/immutablematrices.html#module-sympy

but should presumably link to:

https://docs.sympy.org/1.6.1/index.html

[oscarbenjamin]

I'm not sure how intersphinx works. What would need to be changed to affect that?

[cstarkjp]

Intersphinx expects an objects.inv file at the given URL. This doc inventory file is presumably regularly re-created at the Sympy end, but I'm not aware of how. Perhaps using sphobjinv?

[oscarbenjamin]

Presumably this is handled in the docs repo:
https://github.com/sympy/sympy_doc

[asmeurer]

Is the intersphinx for https://docs.sympy.org/dev working correctly?

Perhaps there was a bug when building the 1.6.1 docs. Maybe rebuilding them with the latest Sphinx and copying the objects.inv will fix it?

[cstarkjp]

Using 'sympy': ('https://docs.sympy.org/dev', None) does work (inasmuch as it directs to the dev pages) - thanks for that.

And yes, a rebuild against the current stable Sphinx (3.1.2 today) and its StandaloneHTMLBuilder should provide a working objects.inv.

Is there some way that, pre the next release, a test for a correct (and correctly located) objects.inv can be added to the testing cycle?

Just to be clear: we're not talking about a rebuild of the Sympy docs at the user end are we?

[asmeurer]

I mean we should manually patch the docs repo https://github.com/sympy/sympy_doc.

Is there some way that, pre the next release, a test for a correct (and correctly located) objects.inv can be added to the testing cycle?

If we can figure out how to make a test for that, we should do it. Although I'm unclear how this broke. Was it a bug in Sphinx or some issue with our configuration?

[cstarkjp]

To recap how this broke: From what (little) I understand of Sphinx, it simply requires that inventory objects.inv to be present (and correctly configured for that location) at the root URL for the project, which should logically be https://docs.sympy.org.

Since there is currently no such file there, users will logically try e.g. https://docs.sympy.org/latest or https://docs.sympy.org/1.6.1, both of which indirect to the latest Sympy mod (immutable matrices today), which isn't desirable.

So, whatever is done at the Sympy end when building the Sphinx docs it's imperative (?) it produces and places objects.inv at the root (anyone else here a Sphinx expert?).

I don't think it's a bug, so much as an oversight in the way Sphinx is deployed. I wish I could be more helpful: I'm only a consumer of Sphinx and Intersphinx, and I've yet to have to build my own objects.inv.

[sylee957]

I see #19430 had changed the way sympy reference in immutable matrix, so maybe it can be related.

[oscarbenjamin]

Using 'sympy': ('https://docs.sympy.org/dev', None) does work (inasmuch as it directs to the dev pages) - thanks for that.

What page exactly does it link to?

I see #19430 had changed the way sympy reference in immutable matrix, so maybe it can be related.

Yes, that looks like the fix. I guess that it links to the modules page i.e.:
https://docs.sympy.org/latest/modules/index.html

Is that what we want?

[cstarkjp]

What page exactly does it link to?

It links to https://docs.sympy.org/dev/modules/index.html#module-sympy

Yes, that looks like the fix. I guess that it links to the modules page i.e.:
https://docs.sympy.org/latest/modules/index.html

Is that what we want?

Yes, I believe it is. Thanks!!!

[oscarbenjamin]

I'm thinking about a 1.6.2 release. If you want to open a PR that applies the fix from #19430 to the 1.6 branch then this will be fixed when I rebuild the docs for the new release.

[oscarbenjamin]

I'm going to release 1.6.2. If anyone wants to submit a PR for this then we can fix it in that release

[oscarbenjamin]

Everything else for 1.6.2 is resolved so if anyone wants to open a PR backporting the fix for this to the 1.6 branch then this will be fixed when 1.6.2 is released (very soon).

[asmeurer]

To recap how this broke: From what (little) I understand of Sphinx, it simply requires that inventory objects.inv to be present (and correctly configured for that location) at the root URL for the project, which should logically be https://docs.sympy.org.

Wait, so are you saying it has to be at the base of the URL, not a sub-URL? That seems extremely restrictive. There are a lot of examples of documentation that only exists at sub-URLs. For instance, any project documentation hosted on GitHub pages without a custom URL will be at https://org.github.io/project (I do this myself for quite a few projects).

[asmeurer]

Also, the 1.6.1 slug is there on accident. There should only be dev and latest. We will probably make 1.6 and 1.6.1 do redirects to latest to avoid breaking URLs. See #19839

[oscarbenjamin]

I think this is fixed in #19881. The fix won't show until I do the release and then update the docs though

[oscarbenjamin]

@cstarkjp can you confirm whether this is still an issue?

[cstarkjp]

I'll be able to check again in a day or two

[oscarbenjamin]

Thanks. I'm preparing to release 1.7 so if this isn't fixed it would be good to get it fixed before the release

[oscarbenjamin]

@cstarkjp I think this should be fixed if you test with the dev docs URL: https://docs.sympy.org/dev/

Hopefully it will get fixed for the main docs when I update the docs repo after releasing 1.7.

I'm not really sure how to test it though...

[bskinn]

Wait, so are you saying it has to be at the base of the URL, not a sub-URL? That seems extremely restrictive. There are a lot of examples of documentation that only exists at sub-URLs. For instance, any project documentation hosted on GitHub pages without a custom URL will be at https://org.github.io/project (I do this myself for quite a few projects).

No, objects.inv can reside at a sub-URL. The entire ReadTheDocs ecosystem is set up this way.

Take a look at my PyOhio 2019 talk on intersphinx, especially starting around 12:00, for what's going on with the interplay between intersphinx_mapping, objects.inv, and the URL hierarchy of a docset. Happy to field any further questions (including with the original issue, though I'd need more information and context--it's not clear exactly what was going wrong)!

[oscarbenjamin]

@cstarkjp is it possible to verify if the issue is fixed using the dev docs URL? Otherwise I guess we won't know until I push the new docs after the release.

[oscarbenjamin]

Is this fixed now?

[cstarkjp]

I believe so!

…

On Jun 28 2022, at 05:46 jptyo, Oscar Benjamin ***@***.***> wrote: Is this fixed now? — Reply to this email directly, view it on GitHub <#19788 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA4MWBLX25WYJSGAOTRHTETVRIHLXANCNFSM4O5TDNHA>. You are receiving this because you were mentioned.

[oscarbenjamin]

Thanks @cstarkjp. I'll close this now. Please say if you find a new problem.