Make pushing summary to first line optional

[KelSolaar]

Hi,

It is common with Sphinx to write module titles that can be used with sphinx-apidoc and autodoc, for example, the Sphinx Gallery plugin uses them.

We also do use them but unfortunately, the title gets pushed back on the first line:

"""Spectral Uniformity
===================

Defines the objects to compute the *spectral uniformity*
(or *spectral flatness*) of spectral distributions.

References
----------
-   :cite:`David2015a` : David, A., Fini, P. T., Houser, K. W., Ohno, Y.,
    Royer, M. P., Smet, K. A. G., Wei, M., & Whitehead, L. (2015). Development
    of the IES method for evaluating the color rendition of light sources.
    Optics Express, 23(12), 15888. doi:10.1364/OE.23.015888
"""

I was wondering if there is a case to bypass the formatting of the two first lines.

Cheers,

Thomas

[DanielNoord]

I'm wondering if we should make pushing the summary of multi-strings back to the first line optional. It's not actually "demanded" by the PEP and just something I added as it was easy to implement. I think it makes sense to make it optional.

[KelSolaar]

That would make sense to me! I found the related conversation on Pydocstyle that I was looking for before opening this issue: https://github.com/PyCQA/pydocstyle/issues/418

[DanielNoord]

@KelSolaar Just to get this right myself: 1) Do titles still require a period after their summary? I think not enforcing the period runs counter to what the PEPs say. I'd like to stick to them to avoid too much discussion about semantics/details (that's what this tool is aiming to avoid anyway). 2) Can the second line only be made up of ==== or are there other patterns we should allow?

[KelSolaar]

Hi,

1. I think that the period would not be needed in that case.
2. RST, afaik, does not enforce usage of equal to mark the title header, it uses whatever symbol comes first, then the second and so forth to define the hierarchy. Put another way:

My Title
========

My Section
----------

My Sub-Section
^^^^^^^^^^^^^^

Should be equivalent to

My Title
********

My Section
^^^^^^^^^^

My Sub-Section
==============