How can I use the only directive inline by using role in python-sphinx?

Question

In python-sphinx there is the only directive, which can be used to conditionally influence the document according to its output. For instance text appears in html or latex only.

It is use like this:

.. only:: not latex

   Here there is some Text, that does not appear in latex output.

.. only:: html

   Here there is some Text, that only appears in html output.

How can I use the role directive in the right way to use the only-class inline, let's say like this:

Here there is some Text, that :only-notlatex:`does not appear in latex`
:only-html:`only appears in html`.

I saw something similar for the raw directive. Is this also possible for the only directive? I tried:

.. role:: only-html(only)
   :format: html

.. role:: only-notlatex(only)
   :format: not latex 

But this does not work.

Baucom

Do not confuse directives and roles. Directives work on blocks of text (whole paragraphs); roles are for inline text (within paragraphs). There is no built-in role that corresponds to the only directive. You will have to create your own custom role for this purpose. I can't provide any detailed instructions, but here is an article that can help you get started: doughellmann.com/2010/05/09/…. – Idealist

OK, thank you. This makes sense. I got confused since I thought raw is a directive and for this it works. But as stated here, this seems to be "a special case". – Baucom

I turned my comment into a proper answer. – Idealist

Answer 1

Directives work on blocks of text (whole paragraphs); roles are for inline text (within paragraphs).

You mentioned raw, and there is indeed both a directive and a role with that name, for "raw data pass-through".

But there is no built-in role that is the inline equivalent of the only directive. You will have to create your own custom role for this purpose. I can't provide any detailed instructions, but here is an article that can help you get started: http://doughellmann.com/2010/05/09/defining-custom-roles-in-sphinx.html.

Idealist

Answer 2

For output-dependent inline content, you may consider substitutions that can be nested in "only" directives.

.. only:: html
   .. |writer-name| replace:: html5
.. only:: latex
   .. |writer-name| replace:: latex

This document was converted by Sphinx's |writer-name| writer.

or custom roles with to-be-skipped classes:

.. role:: no-latex
.. role:: no-html

Here there is some Text, that :no-latex:`does not appear in latex`
:no-html:`does not appear in html`.

together with Docutils' strip-elements-with-classes configuration setting.

Litmus

I advise readers to ignore the solution in the 1st code fence of this answer as it'll only make your code more confusing and there's no expressed need for using substitutions there. I'm inclined to say this repeats the previous answer without adding anything significant. – Dott

One advantage over "raw" is that you can use rST syntax (e.g. for a link) inside the replacement. Another use case is settings where "raw" is disabled for security reasons. – Litmus

The first example is a workaround in pure rST, while implementing an "only" base role enabling custom roles like .. role:: only-html(only)\n :format: html can only be done in a Python extension or modification. – Litmus