References issue #26927.

This PR aims to improve documentation by including a link to an example file that compares dimensionality reduction techniques to the doc string of the manifold.MDS class.

Other Comments

Consider the below proposal for

1. a new use of the See Also section, and of
2. a new convention for where in doc strings to place links to example files.

Observations

1. There is not consensus by maintainers about where in the doc string developers should place links to an example files.

   • The creator of the referenced issue, 26927 , made an example PR wherein the link is in the main section of the doc string. The link is in the same location in the latest version of main.
   • The most recent (as of 2023-09-25) PR originally placed the link in the main section but was advised to move it to the examples section. After the move, the PR was approved.
   • Another recent PR originally placed the link in the See Also section but was advised to move the link to the main section. After the move, the PR was approved. The link is still in the main section.

2. The Developer's Guide says that example files might

   • demonstrate use
   • compare different algorithms
   • et cetera.

3. The See Also section of doc strings is meant to be a list of FCMs (functions/classes/methods) for similar algorithms.

4. Personally, I would appreciate finding link to detailed examples in the Examples section of doc strings just below the code snippet examples (in case the code snippets are not enough).

5. Personally, I would appreciate finding a link to an example file that compares similar algorithms in the doc string just after the list of similar algorithms.

6. Personally, I do not look for examples OR comparisons in the main section of a doc string; I look there for a simple statement of what the FCM does. (cf. @adrinjalali 's response to @ArturoAmorQ about prominent content.)

Opinion

I would make the following convention for this meta-issue #26927:

1. If an example file gives a demonstration of an FMC with a level of detail beyond that available in the code snippets, then the link to the example file goes at the bottom of the Examples section of the doc string for the FMC with the wording "For a more detailed example, see ..."
2. If an example file gives a comparison of related FMCs, then the link to the example file goes at the bottom of the Also See section of the doc string of the FMC with the wording "For a comparison of similar algorithms, see ...".

Trade-offs

1. The See Also sections are, as of now, consistently and cleanly lists of related FCMs. My suggestion introduces a new use for the section, reducing consistency of use of the section.
2. This (meta)-issue is inviting to first time contributors (like myself). Adding too many details will make it less inviting.
3. In trying to put a link in the Also See section, I have found that some of the GitHub checks do not pass.