Weird indent for C++ template signatures

[2bndy5]

We're considering a switch to this theme for the breathe extension's docs, but we discovered that templated class signatures have weird indentation.

.. cpp:class:: template< typename T6 > \
               TemplateClassTester< T6* >
   
   Some description.

which renders as

and here's the HTML output

<dt class="sig sig-object cpp" id="_CPPv4I0ENUt22_ex_class_template_spec19TemplateClassTesterIP2T6EE">
    <span id="_CPPv3I0ENUt22_ex_class_template_spec19TemplateClassTesterIP2T6EE"></span><span class="k">
        <span class="pre">template</span>
    </span>
    <span class="p"><span class="pre">&lt;</span></span>
    <span class="k"><span class="pre">typename</span></span>
    <span class="w"> </span>
    <span class="sig-name descname"><span class="n"><span class="pre">T6</span></span></span>
    <span class="p"><span class="pre">&gt;</span></span>
    <br>
    <span class="k"><span class="pre">class</span></span>
    <span class="w"> </span>
    <span class="sig-name descname">
        <span class="n">
            <span class="pre">TemplateClassTester</span>
        </span>
    </span>
    <span class="p">
        <span class="pre">&lt;</span>
    </span>
    <a class="reference internal"
        href="#_CPPv4I0ENUt22_ex_class_template_spec19TemplateClassTesterIP2T6EE"
        title="[anonymous]::TemplateClassTester<T6*>::T6">
            <span class="n"><span class="pre">T6</span></span>
    </a>
    <span class="p"><span class="pre">*</span></span><span class="p"><span class="pre">&gt;</span></span>
    <a class="headerlink" href="#_CPPv4I0ENUt22_ex_class_template_spec19TemplateClassTesterIP2T6EE"
        title="Permalink to this definition">#</a>
    <br>
</dt>
<dd>
    <p>Some description.</p>
</dd>

We have taken a little liberty with the coloring for preference reasons, but we have not altered any CSS that could be causing this strange indent.

Cause

From what I can tell the span elements are inheriting from the .sig CSS rule:

.sig {
  background: var(--color-api-background);
  border-radius: .25rem;
  font-family: var(--font-stack--monospace);
  font-size: var(--api-font-size);
  font-weight: 700;
  padding: .25rem .5rem .25rem 3em;
  text-indent: -2.5em;
}

for which the problematic SASS seems to be

furo/src/furo/assets/styles/content/_api.sass

Lines 51 to 53 in 6b6610f

	// These are intentionally em, to properly match the font size.
	padding-left: 3em
	text-indent: -2.5em

Is this desired behavior?

I found it weird that the signature has such a large padding-left value then compensates with a negative indent (which only affects the first of multiple lines). I'm not sure what led to this design decision, but it seems like it wasn't initially designed for multi-line signatures.

[2bndy5]

@pradyunsg Should this be elevated to an issue? I have a PR pending this question's answer. There's no real rush, but it has been a few months.

I know you've been busy on more pressing matters, and I fully appreciate all your hard work with executablebooks org and sphinx.

[2bndy5]

For now, I'm fixing this with a temporary solution in our docs' custom CSS:

.sig {
  padding-left: 0.5em;
  text-indent: revert;
}

[pradyunsg]

@pradyunsg Should this be elevated to an issue?

Once we have a clear answer on what to do here, yes. I don't think we do yet.

There's no real rush

I appreciate this! It's a sentiment that isn't usually expressed often enough, and I want to explictly note that it's appreciated. :)

---

Notably, I feel like blanket removing indentation triggers a regression in other cases though, and it's a tradeoff. Ideally, the Sphinx PR with multi-line signatures by default lands (sphinx-doc/sphinx#11011) and I can just yank out these indentation shenanigans.

[BurningEnlightenment]

This formatting initially surprised me, too. But I think I finally understand the intention. In virtually every other case there is no multi-line signature, but overflow from a single line signature. And in these cases it makes sense to indent everything but the first line:

Obviously this is a bummer for template heavy libraries, but I see no good way to fix this 😕

[2bndy5]

In the sphinx-immaterial theme, we patched the domains' parameter objects to include a CSS class unique to multi-line signatures (which we determine as anything over 70 chars long). Then we can use CSS to add content: "\a " to the parameters' pseudo element (::before).

The sphinx-immaterial theme also allows use of clang-format for C/C++ signatures (and optionally utilize a user-defined clang-format config).

[BurningEnlightenment]

W.r.t. sphinx-immaterial: While I appreciate the amount of work spent on improving the C++ documentation story, I'm a little skeptical about being tied to a specific theme… Apart from the clang-format stuff, it sounds like the right place for those features would be sphinx itself.

[pradyunsg]

FWIW, this isn't limited to C++ and is intended to be visually distinct indentation for long snippets of API reference that need to be wrapped. See https://pradyunsg.me/furo/kitchen-sink/api/#furo._demo_module.show_warning for example.

I have been involved in discussions on Sphinx (sphinx-doc/sphinx#11011) to improve how long signatures are handled, and making them work better. Until that lands, I'm not particularly keen on changing things in Furo to tweak how stuff works. I'm also wary of relying on external tools to format API reference samples -- I'm not interested in maintaining a documentation site generator as a part of a Sphinx theme and would rather that either (a) someone develop an extension that does things better for C++ code and I'll add support in Furo for it, or (b) things improve in Sphinx itself (like the aforementioned PR).

[pradyunsg]

Lemme clarify: I'm not too keen on changing things around making Furo tweak the generated markup -- I'm on board for ideas for tweaking how Furo handles this situation and improving it.

[BurningEnlightenment]

I have been involved in discussions on Sphinx (sphinx-doc/sphinx#11011) to improve how multiline signatures are handled, and making them work better. Until that lands, I'm not particularly keen on changing things in Furo to tweak how stuff works.

I wasn't aware of said PR, but I agree with you that it makes the most sense await those changes.

I'm also wary of relying on external tools to format API reference samples -- I'm not interested in maintaining a documentation site generator as a part of a Sphinx theme

Thank you, this is also something that would be a turn off for me; I'm much more keen on things which do just one thing but do it well :)

[pradyunsg]

I'm gonna say this will be resolved by #761 and can be consolidated into that.