.. confval:: translation into LaTeX

[cahash00]

Hello! First time posting! I am a part of a dev team that uses Sphinx to build our documentation. We build the static html version, but we also build the pdf vesion using the sphinx-latex. However, we are seeing that large / long entries for the rst entry: .. confval:: does not split for long lines and goes off the page. I have tried several things including 'sphinxsetup': 'verbatimforcewraps, verbatimmaxunderfull=12', from this issue. Does anyone know how to split long lines? Or even at a basic level, what does sphinx translate the confval type to on the LaTeX side?

[AA-Turner]

Do you have an example/reproducer? It's very hard to help without one.

A

[cahash00]

Sorry! I came up with a minimum working example here. Attached the files at the bottom. Details about the environment:
clean virtual environment with python/3.13 and sphinx/8.2.3. Command to build:

sphinx-build -b latex . _build/latex
cd _build/latex
make

conf.py file below:

# -*- coding: utf-8 -*-

import sys
import os
import re
import datetime

latex_documents = [
  ('index', 'foobar.tex', 'FooBar',
   'Bar, Foo', 'manual'),
]

foo.rst file below:

#######
Foo Bar
#######

Here is a long configuration value that does not linewrap:

******
FooBar
******

testing
"""""""

.. confval:: this is a very long string that is supposed to have some sort of line-wrapping when it gets too long but instead it just goes off the page.

:type:
   ``string``
:options:

.. _foo:

   :all:

      Activate all options.


.. _bar:

   :selected:

      Select which options to activate.


.. _foo_bar:

   :none:

      Do not use any options.


Done.

index.rst file below:

MWE for long "confval" issue
=====================================

.. toctree::
      :maxdepth: 2
      :caption: Contents:

      foo

[jfbu]

Thanks for the mwe. For some reason the output uses the LaTeX "tilde" which is mark-up for a non-breakable space:

{\sphinxbfcode{\sphinxupquote{this~is~a~very~long~string~that~is~supposed~to~have~some~sort~of~line\sphinxhyphen{}wrapping~when~it~gets~too~long~but~instead~it~just~goes~off~the~page.}}}

I had never seen tildes in Sphinx LaTeX output, but one learns at all ages.

This works as workaround, add it to conf.py:

latex_elements = {
    'preamble': r"""
\let\orisphinxbreaksviaactive\sphinxbreaksviaactive
\def\sphinxbreaksviaactive{\orisphinxbreaksviaactive\def~{ }}
""",
}

When time permits I will look closer into it to check when Sphinx LaTeX outputs such "tildes" more generally and if we should do something about it.

[jfbu]

(by the way, I should but do not usually check discussions, but I clicked on my notifications in the github interface by pure coincidence tonight and it was at top)

[AA-Turner]

@jfbu I think it's because sphinx.domains.std.ConfigurationValue.handle_signature() uses a addnodes.desc_name() node, and sphinx.writers.latex.LaTeXTranslator.visit_desc_name() then sets literal_whitespace, which replaces spaces with tildes. Perhaps the confval directive should use a different node type?

A

[jfbu]

The 'sphinxsetup' options you mentioned like verbatimforcewraps have no effect on inline literals, they are only for code-blocks. The option for inline literals is inlineliteralwraps but it already defaults to "true". This is why \sphinxbreaksviaactive is executed by \sphinxupquote and we can use it as a hook point to locally redefine the tilde.

[jfbu]

Perhaps \sphinxupquote should do the \def~{ } if inlineliteralwraps has its default value "true", in which case that could deserve being opened as a real issue on the issue tracker.

[jfbu]

This will be fixed in 8.3.0, see #13817. To obtain same output with a small red symbol indicating the whitespace before linebreak, you will need to remove from conf.py the workaround.