Allow relative links to other parts of the documentation

pquentin commented 3 months ago

🚀 Feature Proposal

Relative links in the Markdown description should be interpreted as links to endpoint and/or namespaces:

cat would link to the cat namespace, such as https://elasticsearch-py.readthedocs.io/en/v8.14.0/api/cat.html for Python.
cat.aliases would link to the specific function, such as https://elasticsearch-py.readthedocs.io/en/v8.14.0/api/cat.html#elasticsearch.client.CatClient.aliases in the documentation.

There's a catch with global endpoints, such as search or bulk. Should they be defined as _global.bulk or just bulk? The Python link is https://elasticsearch-py.readthedocs.io/en/v8.14.0/api/elasticsearch.html#elasticsearch.Elasticsearch.bulk.

The OpenAPI export would use links that work for the Serverless OpenAPI docs. Currently, there's no grouping, so for like cat.aliases it would #endpoint-alias according to https://github.com/elastic/elasticsearch-specification/pull/2746/files#diff-4f456691f5983599680ab2e423b475e86dc8ea112ef4e7ed91e691cc6c14c567.

Using other forms of grouping than namespaces is out of scope.

Motivation

Linking between endpoints is useful. The current use case is linking from the human-friendly cat APIs to the corresponding machine-friendly API.

Example

Please provide an example for how this feature would be used.

/*
 * Get aliases.
 * 
 * Retrieves the cluster’s index aliases, including filter and routing information.
 * The API does not return data stream aliases.
 * > [!NOTE]
 * > CAT APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use [the Aliases API](#alias).
 */

Open questions

Should we use a prefix to make it clear that the link is relative?
(Does our API docs support GFM admonitions?)

shainaraskas commented 3 months ago

The OpenAPI export would use links that work for the Serverless OpenAPI docs. Currently, there's no grouping, so for like cat.aliases it would #endpoint-alias according to https://github.com/elastic/elasticsearch-specification/pull/2746/files#diff-4f456691f5983599680ab2e423b475e86dc8ea112ef4e7ed91e691cc6c14c567.

I don't think this is exactly correct. cat.aliases would be #operation-cat-aliases and the aliases grouping would be #endpoint-alias

linking to these docs, respectively: operation-cat-aliases, endpoint-alias

Re the link format, I wonder if we can take both the label and the anchor format out of the hands of the author so we can be more specific when referring to endpoints (or, in the case of clients, the equivalent method(?))

using $ markup as an example, but I'm not fussy and we can use whatever is ideal in this ts markdown hybrid situation

so:

... For application consumption, use $cat.

outputs as:

For application consumption, use [the Cat API](#endpoint-cat).

or 

For application consumption, use [Cat endpoints](#endpoint-cat).

and

... Use $cat.aliases instead!

outputs as

Use [the /_cat/aliases endpoint](#operation-cat-aliases) instead!

and in the python client docs as

Use [the CatClient.aliases() method](python link) instead!

flobernd commented 3 months ago

Commenting @swallez proposal here as well for completeness.

Instead of using custom tags/anchors in the markdown, we should stick to standard markdown and use links with custom URI schema for linking to endpoints or groups/namespaces:

please refer to the [bulk endpoint](endpoint://bulk).

This allows us to use regular markdown parsers, to use references in mid-text and as well provides a good way to specify the link and a (fallback-) description for the link at the same time.

Similar to this, we could use other URI schemas like namespace: or even doc:, if we want to place a relative link to the official documentation website here that would be agnostic to the flavor (stack|serverless).

flobernd commented 3 months ago

@shainaraskas I would be fine using the docs description in the client as well to not overcomplicate things.

Not sure how it is in other languages, but in .NET I would translate such links to something like this: <see cref="CatNamespacedClient.SomeMethod()" />. This reference tag is rendered as a highlighted text that mentions the method name which means that I would completely ignore the Markdown link description in these cases.

pquentin commented 3 months ago

I don't think this is exactly correct. cat.aliases would be #operation-cat-aliases and the aliases grouping would be #endpoint-alias

Oh, so you already have namespace information, then. Thanks for the correction!

So, merging both proposals would give us:

... For application consumption, use [the cat APIs](namespace://cat)

... Use [the /_cat/aliases endpoint](endpoint://cat.aliases) instead!

Despite my preference for API names, I agree that having the same text in the docs and client is fine as long as there's a link in the client.

shainaraskas commented 3 months ago

Oh, so you already have namespace information, then. Thanks for the correction!

Currently, it's grouped by path rather than namespace, which is where we are running into a little friction. a lot of index API endpoints are being grouped under root for example.

pquentin commented 3 months ago

I'm not sure what would be the correct name. Those endpoints are in the _global folder of the specification as they are not part of any namespace: https://github.com/elastic/elasticsearch-specification/tree/main/specification/_global

elastic / elasticsearch-specification