Documentation links in error messages.

[provinzkraut]

Can we still include a link to the relevant docs, please? This will point the user in the right direction, irrespective of their intent

Originally posted by @AgarwalPragy in #2765 (comment)

---

The question stands whether we want to include links to the documentation in error messages.

[provinzkraut]

I'll repost my original answer here

---

I'm not entirely against this, but since we're currently not doing this anywhere else, I think we should have a general discussion about this first.

Adding those links will also add some maintenance burden, as we'll have to ensure they're all valid (some pages might move), update with the version, and stay semantically correct as the docs change. Nothing is more frustrating than a dead of nonsensical link.

I also think that if we were to do this, we shouldn't do it just in this case, but more broadly. We could for example opt to employ a system like SQLAlchemy has, where all of these exception classes have their own error code, for which an explanation in the docs exists, linking to further reading material.

[JacobCoffee]

I quite like the idea similar to SQLA's

ProgrammingError: (sqlalchemy.dialects.postgresql.asyncpg.ProgrammingError) <class 'asyncpg.exceptions.InvalidForeignKeyError'>: there is no unique constraint matching given keys for referenced table 
[SQL: 
CREATE TABLE something (
	...
)

(Background on this error at: https://sqlalche.me/e/20/f405)

I think I'm a fan, just not sure how we will handle the maintenance parts effectively to ensure good DX and not have stale links.

Maybe we can have a GH actions check stale links?

[JacobCoffee]

+1 from Guacs in Discord.

@peterschutt / @cofin ?

@litestar-org/members ?

[peterschutt]

I'm weary about the maintenance burden, but like the idea.

What if we had a section of the docs that specifically housed in-depth explanations of specific issues and those were the sections linked to from exception messages, e.g., https://docs.litestar.dev/2.4/errors/ERR_123.html.

These sections could themselves point to deeper sections of the docs in API or Usage because if we break a link there we'll get alerted to that from the docs build.

Basically, ensure that the docs path that we link to in the exceptions is very unlikely to change.

[JacobCoffee]

A dedicated errors page makes sense, and when I looked at how SQLA does it - its similar:

https://github.com/sqlalchemy/sqlalchemy/blob/86f335c29e9f4d9a8e2b28dd75301f28f5f9f4f1/doc/build/errors.rst?plain=1#L176

errors.rst for the main errors page, and anchor links hidden for the codes
e.g., https://sqlalche.me/e/20/f405 (link shortener) -> https://docs.sqlalchemy.org/en/20/errors.html#error-f405 -> https://github.com/sqlalchemy/sqlalchemy/blob/86f335c29e9f4d9a8e2b28dd75301f28f5f9f4f1/doc/build/errors.rst?plain=1#L304

[peterschutt]

Oh cool, well I'd definitely support doing something similar.