phpDocumentor / guides

Guides library to parse documentation
MIT License
32 stars 15 forks source link

[Bug]: Roles cannot be checked as they are not defined #925

Open brotkrueml opened 7 months ago

brotkrueml commented 7 months ago

Summary

Roles, like

:sql:`SELECT * FROM table`

are not defined, so typos or unsupported roles cannot be warned about, like (mind the g instead the q):

:sgl:`SELECT * FROM table`

In Sphinx, custom roles have to be defined: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#inline-code-highlighting

On rendering, Sphinx displays an error about an unknown role:

 ERROR: Unknown interpreted text role "sgl".

This way, the user can spot the error and correct it.

Guides holds no definition of custom roles and therefore cannot warn about it.

jaapio commented 2 months ago

@linawolf it looks like the \phpDocumentor\Guides\RestructuredText\TextRoles\DefaultTextRoleFactory we do collect the roles that are known by the parser. I think we can use trigger a warning when we fall back to the generic role. But that seems not always valid to me as you can set the default role via a directive. Which makes this expected behavior. On the other hand it would be nice if we could detect typo's what do you think?