2

Is it possible to condtionally define a target in a reStructuredText file using ifconfig?

I've set a variable in my sphinx conf.py file that I want to use to conditionally determine the URI of a target in my documentation:

def setup(app):

    argv = ' '.join(sys.argv)
    if '-b html' in argv:
        app.add_config_value('buildername', 'html', 'env')
    else:
        app.add_config_value('buildername', 'not-html', 'env')

And my index.rst file has the following content:

test link to target1_

.. ifconfig:: buildername == 'html'

  .. _target1: https://example.com/a

The above works as expected, and "target1" becomes a hyperlink to example.com/a

But if I want to actually define target1 to be conditionally set to one of two options based on the value of the buildername config var, then I have

test link to target1_

.. ifconfig:: buildername == 'html'

  .. _target1: https://example.com/a

.. ifconfig:: buildername != 'html'

  .. _target1: https://example.com/b

Not only does the above output not work for example.com/b, but it breaks the first link and target1 now points to nothing (actually #id3).

Moreover, I get the following warnings in my sphinx-build output

user@host:~$ make clean && sphinx-build -b html . _build/html/
...
reading sources... [100%] support                                               
.../index.rst:16: WARNING: Duplicate explicit target name: "target1".
.../index.rst:8: WARNING: Duplicate target name, cannot be used as a unique reference: "target1".
...

Is it possible to define the same target twice within a .rst file, such that each definition is wrapped in an ifconfig directive?

Michael Altfield
  • 2,083
  • 23
  • 39
  • 1
    I think this is related to similar issues with the `only` directive. See https://github.com/sphinx-doc/sphinx/issues/2150 – mzjn Jul 28 '20 at 08:46

1 Answers1

1

Unfortunately, I do not think what you want is possible. You could suppress warnings (which is probably not a good idea), or you could add more markup to avoid them through a one-to-one relationship between target and link.

.. ifconfig:: buildername == 'html'

    test link to target1_

.. ifconfig:: buildername == 'html'

    .. _target1: https://example.com/a

.. ifconfig:: buildername != 'html'

    test link to target2_

.. ifconfig:: buildername != 'html'

    .. _target2: https://example.com/b
Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • is it possible to suppress a specific subset of warnings? – Michael Altfield Jul 28 '20 at 09:11
  • 1
    Yes: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-suppress_warnings. However it looks like this type of warning cannot be suppressed. Try out all the options and see if you still get this warning type. If it cannot be suppressed, you could ignore the warnings. – Steve Piercy Jul 28 '20 at 09:38
  • Is it really necessary to have four `ifconfig` directives? – mzjn Jul 29 '20 at 09:09
  • Yes, assuming that each `ifconfig` is located in discontiguous places across the documentation. – Steve Piercy Jul 29 '20 at 12:25