Formatting "template <typename T>" part of C++ declarations

[shimizukawa]

Hi,

I understand this is a pretty subjective request, but I would like to be able to specify a C++ function with template parameters like:

#!rst

.. cpp:function:: template <typename T>
                  SymmetricAerodynamics::set_kind()

And have it render as:

template <typename T>
SymmetricAerodynamics::set_kind()

Currently it will render as two separate functions in the final output or if you put it on one line then it comes out as one line:

template <typename T> SymmetricAerodynamics::set_kind()

In other documentation tools (eg. doxygen) and generally in C++ code layout the template< typename T> part goes on the line above. I would also be happy to specify it on one line and have Sphinx automatically insert the line break.

If this seems like a reasonable thing to support then I would be happy to try to look into implementing it. My interest is in part driven by my work on the Breathe Sphinx extension which generally deals with C++ and would benefit from this multi-line support in the rendering of desc_signature node.

I realise the impact of this change my be considered to be breaking/changing current behaviour and so cannot be done.

Cheers,
Michael

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/1314
• Originally reported by: michaeljones
• Originally created at: 2013-11-25T06:34:49.453

[christophercrouzet]

I'm intending to use sphinx to manually document C++ projects that heavily rely on templates but this is issue doesn't help with the readability factor—too bad it's marked as a low priority.

[Oberon00]

Same here! Since doxygen is basically unusable for template heavy C++-code, Sphinx is a nice alternative. But until this is implemented, I will have to use rst sections for my functions.

[jakobandersen]

I would like to implement it when I find time, but there are 3 separate issues of which I need a bit of help with the last two:

• Template declaration support in the domain. I will try to start on this soon.
• Rendering multi-line declarations. I guess it's easy to render a line break, but I have not found out how.
• Support for multi-line declarations. The declarations are split somewhere before they reach the domain, and I don't know if it's possible for a domain to disable the splitting.

[jakobandersen]

A declaration can be split over multiple lines by escaping the line break. For example:

.. cpp:class:: template<typename T> \
               MyClass

Each line of template parameter lists should be rendered on their own line.