[BUG] Link checker fails when adding relative URLs

[dblock]

What is the bug?

Coming from https://github.com/opensearch-project/opensearch-py/pull/537/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5 the link checker does not like [page](link) when link is a relative link to source code. These work on GitHub.

How can one reproduce the bug?

• If you add a relative link, CI will fail on it as in https://github.com/opensearch-project/opensearch-py/actions/runs/6509630345/job/17681533560

### Errors in docs/source/README.md
* [file:///home/runner/work/opensearch-py/opensearch-py/docs/source/samples](file:///home/runner/work/opensearch-py/opensearch-py/docs/source/samples): Failed: Cannot find file
* [file:///home/runner/work/opensearch-py/opensearch-py/docs/source/benchmarks](file:///home/runner/work/opensearch-py/opensearch-py/docs/source/benchmarks): Failed: Cannot find file

• If you add a new link to something that doesn't exist, CI will fail on it as in https://github.com/opensearch-project/opensearch-py/actions/runs/6511677337/job/17687825863?pr=537

### Errors in README.md
* [https://github.com/opensearch-project/opensearch-py/tree/main/benchmarks](https://github.com/opensearch-project/opensearch-py/tree/main/benchmarks): Failed: Network error

What is the expected behavior?

• Allow one to add a new relative link.
• Link checker should pass.

[saimedhi]

I think the problem is not with link checker. We have a copy of README.md in docs/source. That is causing problem when relative path is given.

[dblock]

I think the problem is not with link checker. We have a copy of README.md in docs/source. That is causing problem when relative path is given.

Oh! It's a soft link too, not a copy!

[Krish-2505]

I cannot see logs from these links, maybe the logs are expired. so it will be helpful for me to contribute if you can provide some context/screenshots of these logs.

[dblock]

@Krish-2505 add a relative link to any doc and submit a draft PR, it should fail.

[Krish-2505]

@dblock I attempted to include a relative link, but the link checker did not detect any failures. it detected failures when I added a link that didn't exist.

[Krish-2505]

@dblock In the file DEVELOPER_GUIDE.md, the link highlighted in yellow does not exist, and the link checker is failing because of this non-existent link. However, the link checker is not failing for the other relative links that were added to any doc.

[dblock]

I don't see a relative link in your draft PR (https://github.com/opensearch-project/opensearch-py/pull/758), show me a passing link checker on a relative link?

[Krish-2505]

@dblock Here I added one relative link in readme.md in the forked repo and created a pull request, link checker didn't fail here

[dblock]

@Krish-2505 can you please post a link to this change, not a screenshot?

[Krish-2505]

@dblock https://github.com/Krish-2505/opensearch-py/pull/4

[dblock]

@Krish-2505 That's not a relative link.

[https://github.com/opensearch-project/opensearch-py/tree/main/benchmarks](https://github.com/opensearch-project/opensearch-py/tree/main/benchmarks)

A relative link to https://github.com/opensearch-project/opensearch-py/tree/main/benchmarks from https://github.com/opensearch-project/opensearch-py/ would be benchmarks.

[link](benchmarks)

[Krish-2505]

@dblock The link checker is encountering an issue when adding relative links to the README.md file. It seems that the link checker is resolving the relative links incorrectly due to the presence of a soft copy of the README.md file in the docs/source directory. Specifically, when adding a relative link to the README.md file (as shown in this (https://github.com/Krish-2505/opensearch-py/actions/runs/9484199895/job/26133143647)), the link checker fails because it's attempting to resolve the relative link relative to the docs/source directory instead of the repository root. However, when adding a relative link to the developers_guide.md file (as shown in this (https://github.com/Krish-2505/opensearch-py/pull/3)), the link checker does not encounter any issues. so, i think problem occurs due to soft copy of readme file

[dblock]

Yes, this is the problem that needs fixing as pointed out by @saimedhi in https://github.com/opensearch-project/opensearch-py/issues/538#issuecomment-1761987524.

[Krish-2505]

@dblock I've made modifications to the links.yml workflow file to address the issue with relative links in the README.md.

Here's a summary of the changes:

Added a new step before the link checking process. This step removes the symbolic link (soft link) of README.md in the docs/source directory. This prevents the link checker from incorrectly resolving relative links due to the presence of this soft copy.

In the arguments section of the lychee Link Checker, I've added an exclusion for the file reference to the docs/source/README.md. This exclusion is necessary because even though we've removed the soft link, other parts of the project or external references might still point to this location. By excluding it from the link check, we ensure that the checker doesn't attempt to validate any links that might reference this now-nonexistent soft link. This prevents potential false positives or errors that could arise from references to the removed soft link.

After the link checking is complete, I've added another step to recreate the soft link. This ensures that the repository structure remains intact and doesn't affect other workflows that might depend on the presence of this soft link.

After making these change link checker is working as Expected. Check out this pr(https://github.com/Krish-2505/opensearch-py/pull/5). links.yml(https://github.com/Krish-2505/opensearch-py/edit/main/.github/workflows/links.yml)

[dblock]

@Krish-2505 Make a PR into this project and I can take a look?