CODEWITHSUNDEEP
python-sphinxrestructuredtext
Denis Bitouzé
Denis Bitouzé

Reputation: 654

Unknown custom interpreted text role warning

In my Sphinx-doc instance, I have:

But this doesn't work since make html returns:

WARNING: Unknown interpreted text role "LaTeXLogo".

Am I missing something?

Upvotes: 3

Views: 1882

Answers (1)

bad_coder
bad_coder

Reputation: 12890

You have to distinguish 4 things "roles", "directives", "domains" and "options".

Punctuation distinguishes them, in shortened syntax :role: and .. directive::. In complete syntax (without omitting the domain) :domain:role: and .. domain:directive::. Lastly, "options" go under the "directives" and less frequently under "roles", eg:

.. domain:directive::
    :option:

or

:domain:role:

So what is a domain? Most times it refers to a context of a programming language that has roles and directives specific to it. (Notice the sidebar in the documentation for directives is divided into domains).

Having said that let's look at the stated problem:

  • at the end of my conf.py file:

    rst_prolog = """
.. role:: LaTeXLogo
"""

We notice 3 things immediately:

  1. The punctuation used is for a directive, not for a role.
  2. If you check the list of directives (or roles and domains), there's no directive called LaTeXLogo...
  3. ... and neither do you write :role: because each role has a name (the word :role: is just used for generic examples.)

Next we look at the second example:

in some of my .rst files:

:LaTeXLogo:`LaTeX`

Now we notice:

  1. The syntax used is for a role.
  2. In the previous example, LaTexLogo was the "directive argument"...
  3. ... it now reapers as a role.

In conclusion, the only case where the above is used are "Custom Interpreted Text Roles" that have a brief syntax description in the reStructuredText Markup Specification. If we dig deeper a general description is given in reStructuredText Interpreted Text Roles, with a more specific definition in "Creating reStructuredText Interpreted Text Roles", where a constraint on using lower case is present:

Register the Role

  1. Add an entry to the roles dictionary in docutils/parsers/rst/languages/en.py for the role, mapping the English name to the canonical name (both lowercase).

Most users of reStructuredText will probably not need this kind of intricacy. It's well past beginner level and bordering the DTD definition of the docutils parser. If you finally look at "Custom attribute types" a further specification explains the error you were having:

Custom attribute types

In reStructuredText, custom class names can be specified using (...) custom interpreted text roles. Docutils normalizes them to conform to both, HTML4.1 and CSS1.0 name requirements (the regular expression a-z*) via the identifier normalization.

Upvotes: 4

Related Questions