Turn relative paths within docs to absolute links within README markdowns so they are doxygen friendly

[ahsonkhan]

See https://github.com/Azure/azure-sdk-for-c/pull/735#issuecomment-627101719

GitHub renders markdown correctly, when it comes to relative paths, but that doesn't work well for standalone doxygen generated docs.

For example, using [/sdk](sdk) within the root README works and forwards to https://github.com/Azure/azure-sdk-for-c/tree/master/sdk, but the link doesn't get resolved in doxygen.

For information about using a specific client library, see the README file located in the client library's folder which is a subdirectory under the /sdk folder.

Other relative links will result in 404: https://djurekdocs.z5.web.core.windows.net/mono/sdk/core/core/README.md#Porting-the-Azure-SDK-to-Another-Platform

cc @gilbertw, @vhvb1989, @antkmsft, @danewalton, @danieljurek

[danewalton]

I don't think this is needed. This here in the doxygen docs shows relative links should work. I think the example you gave could be fixed by linking specifically to the readme and not the directory:

[/sdk](/sdk/readme.md)

[ahsonkhan]

cc @KarishmaGhiya since you are working on the general problem with links in READMEs and docs (for C/C++, we use doxygen).

One concern with making links point to master (brought up here: https://github.com/Azure/azure-sdk-for-c/pull/853#issue-439522671) is that those links won't resolve in the contributors working branch.

[weshaggard]

Our general guidance around links is posted at https://github.com/Azure/azure-sdk/blob/master/docs/policies/README-TEMPLATE.md and is to use links to master instead of relative links. The primary reason is that the contents of these MD files end up getting used in a lot more context then on github. For example they are consumed by docs, samples, package managers, etc. We used to have the guidance of using relative links but we found more and more folks taking the md files from our repo's and having issues with broken links so we decided to change the guidance to use links to master.

I understand the scenario of links not working in branches when we do that but I think that is a relatively small price to pay in our overall system of where these links are consumed. I will also say that in general the only long lived branch is master and feature branches are typically scoped to a particular time so most folks are browsing source in master.

I will also add that if we are sure the only consumers of a MD file are folks working on github then we can consider using relative links in those cases but for the most part we have found that a lot more places consume these MD files then only on github.

[danieljurek]

In order for this to merge properly we need to ensure that there is a tool in place to convert blob/<branch>/ to blob/<tag>/ in the URL on publishing.

[weshaggard]

Yes that works is part of @KarishmaGhiya's link validation epic https://github.com/Azure/azure-sdk/issues/818

[RickWinter]

@danieljurek please break this issue up into the two issues

[danieljurek]

Split off https://github.com/Azure/azure-sdk-for-c/issues/1044 to track the link validation work. This bug should track the remaining work to turn relative links in the docs to absolute links. I've linked it to the epic https://github.com/Azure/azure-sdk/issues/818

[github-actions[bot]]

Hi @ahsonkhan, we deeply appreciate your input into this project. Regrettably, this issue has remained inactive for over 2 years, leading us to the decision to close it. We've implemented this policy to maintain the relevance of our issue queue and facilitate easier navigation for new contributors. If you still believe this topic requires attention, please feel free to create a new issue, referencing this one. Thank you for your understanding and ongoing support.