Broken link

[DKandrew]

In the documentation logger where it says "Read more in the Experiment Logging use case", the link is broken.

[Borda]

@DKandrew mind send a PR? 🐰

[DKandrew]

Sure! Should I just route the link to this website?

---

Update: I think I can see where the problem comes from, but I don't know how to modify it.

The problem is that the linkage

https://pytorch-lightning.readthedocs.io/en/latest/api/experiment_logging.html

is broken. However, this linkage works properly

https://pytorch-lightning.readthedocs.io/en/latest/experiment_logging.html

Their only difference is the api. I think this is caused by line 91 in this file https://github.com/PyTorchLightning/pytorch-lightning/blob/0914873bc2f588ae592c896460c0c9e6577324cf/pytorch_lightning/loggers/__init__.py#L91

it is using a relative path ./[path],

#  so it is ok if the user is currently in 
https://pytorch-lightning.readthedocs.io/en/latest/loggers.html
# but not ok if user is in 
https://pytorch-lightning.readthedocs.io/en/latest/api/pytorch_lightning.loggers.html

However, I don't know how to

1. Check the path to see if it contains "api"
2. Route the path to the absolute path [src]/experiment_logging.html

[Borda]

Update: I think I can see where the problem comes from, but I don't know how to modify it.

mind check this link generation
https://github.com/PyTorchLightning/pytorch-lightning/blob/0914873bc2f588ae592c896460c0c9e6577324cf/docs/source/conf.py#L348-L382

[Borda]

@DKandrew how is it going, did the link generation helped?

[DKandrew]

@Borda Hi Borda, Sorry I did not look into this because this week is my final week. Could I fix this issue during the weekend?

[Borda]

Sure, and thanks for your help

[DKandrew]

Hi @Borda

After looking into this issue this afternoon. I don't think I can come up with a perfect solution.

The only working solution that I have, is to change the link to the online linkage.

# Change from 
Read more in the `Experiment Logging use case <./experiment_logging.html>`_.
# To 
Read more in the `Experiment Logging use case <https://pytorch-lightning.readthedocs.io/en/latest/experiment_logging.html>`_.

---

The challenge is that the reference link is encoded in the docstring, not in a pure .rst file, so the Custom Anchor solution listed here does not work. The function linkcode_resolve does not help because it seems that it is generating a link to the main body of a Python function/variable, not an unnamed string put on top of the Python file.

I also try these paths

# None of them are working
</experiment_logging.html>
<experiment_logging.html>
</experiment_logging.rst>
<experiment_logging.rst>

# This produces the same result as <./experiment_logging.html>`_
<./experiment_logging.rst>

Similar reference issue is also discovered in this link
https://pytorch-lightning.readthedocs.io/en/latest/api/pytorch_lightning.trainer.html
Again, because of the ../api/.. in the path of HTML, if you try to click

• Multi-GPU training guide
• Multi-node (SLURM) guide
• Any link that does not belong to api folder

You will get the same 404 result.

---

The downside of my solution is that developers have to have a network connection when they test this link, and the link will not direct to their local file (which they may be also developing).

Another automatic solution would be: Flatten the file hierarchy in docs/build so that all the linkages are in the root directory of the html. I think it may work. The build folder does not have to be pretty. After all, we are developing in the source code. But I am not sure how feasible it is technically.

Any Suggestions?

[Kshitij09]

"Read more in the Experiment Logging use case"

I didn't see this line on logger documentation. Is it removed?

[Borda]

@DKandrew as it is a while, I am wondering if this is still valid, mind update?

[DKandrew]

Hello @Borda, it seems like the documentation in the original page is gone, as @Kshitij09 points out. So this case may not be valid anymore.