Help with sphinx documentation

Questions about Python Packaging & Code
1

I’m struggling with the sphinx documentation of my project. I won’t go into details just yet. Right now, I just want to see if someone here could help me out:

  1. I need some help with intersphinx. I’ve added a project I depend upon to my intersphinx_mapping, but only a few links are working. I’m not sure if the error is on my or their side.
  2. I’m having trouble getting the auto generated links (type hints, inheritance, …) working if referenced class is documented, just not where it is defined.

Any help is appreciated.

2

Hey Philip,

I can’t say I have experience with intersphinx. But I could try to find someone that might know–can you tell me what project it is and what specifically isn’t linking?

Can you say a little more about 2 though? Maybe link to an example?
It sounds like you wrote documentation for a class but not in the code itself?

–David

3

Hey David,

for the second point I have an example available here. I’ve asked this before on the sphinx-users group, but got no response.

For the first point, I’ll compile an example and get back to you.

4

@NickleDave I’ve just realized 1. is just a by-product of 2.: If the linked repository is setup as I described in the above example, the auto-generated links also break.

Example:

torch.nn.Module as documented as such, but it is defined in torch.nn.modules.Module.

Using

:class:`torch.nn.Module`

within a docstring works fine. If I base this, the auto-generated inheritance link points to torch.nn.modules.Module which is not part of the documentation and thus breaks the link.

5

To make sure I understand:
you want your link to point to their docs, not their source

but because of how the linked repository is set up, the auto-generated link break if you refer to the docs, but they work if you refer to the source – only they bring a user to raw source code, which is not ideal

6

you want your link to point to their docs, not their source

Correct.

but because of how the linked repository is set up, the auto-generated link break if you refer to the docs, but they work if you refer to the source

Sorry, but I can’t follow. Could you give an example what you mean?