Strange warning

[fredrik-1]

I am working with the matplotlib documentation and wrote a template that generate for example the following file, _as_gen/matplotlib.transforms.Affine2D.rst.

matplotlib.transforms.Affine2D
==============================

.. currentmodule:: matplotlib.transforms

.. autoclass:: Affine2D
   :no-members:
   :show-inheritance:




.. rubric:: Methods

.. autosummary::
   :template: autosummary.rst
   :toctree:
   :nosignatures:

   Affine2D.clear
   Affine2D.contains_branch
   Affine2D.contains_branch_seperately
   Affine2D.from_values
   Affine2D.frozen
   Affine2D.get_affine
   Affine2D.get_matrix
   Affine2D.identity
   Affine2D.invalidate
   Affine2D.inverted
   Affine2D.matrix_from_values
   Affine2D.rotate
   Affine2D.rotate_around
   Affine2D.rotate_deg
   Affine2D.rotate_deg_around
   Affine2D.scale
   Affine2D.set
   Affine2D.set_children
   Affine2D.set_matrix
   Affine2D.skew
   Affine2D.skew_deg
   Affine2D.to_values
   Affine2D.transform
   Affine2D.transform_affine
   Affine2D.transform_angles
   Affine2D.transform_bbox
   Affine2D.transform_non_affine
   Affine2D.transform_path
   Affine2D.transform_path_affine
   Affine2D.transform_path_non_affine
   Affine2D.transform_point
   Affine2D.translate

The template and rendered html pages seems to work as expected but I get the following warning

matplotlib\doc\api\_as_gen\matplotlib.transforms.Affine2D.rst:2: WARNING: Literal block expected; none found.

The overview pages should be equal except for the names but it seems that I only get the warning for some of them. I have tried many different versions with small changes in the template but nothing seems to work without the warning.

Some mistake that I cant see or some kind of bug?

Environment info

• OS: windows and circleCi
• Python version: 3.5, 3.6
• Sphinx version:
• <Extra tools e.g.: Browser, tex or something else>

[fredrik-1]

I found the error. Some of the method docstrings had a first line that ended with ::

I am closing this but I think that the warning message could be improved.

[tk0miya]

Good point. I confirmed with following snippet:

.. currentmodule:: matplotlib.transforms

.. autosummary::

   Affine2D.from_values

I agreed with the error message is not human readable. It should be improved.

[tk0miya]

Finally, I found where the warning comes from. autosummary module generates summary table for methods and classes from their docstrings. At that time, autosummary only picks up the first line of docstring.
The case of the first line contains a literal block notation, the extraction makes it broken.

For example, this is docstring of Affine2D.from_values().

    @staticmethod
    def from_values(a, b, c, d, e, f):
        """
        (staticmethod) Create a new Affine2D instance from the given
        values::

          a c e
          b d f
          0 0 1

        .
        """

I have to say this is not invalid docstring. But autosummary causes a warning for this...

[tk0miya]

Fixed by #5152 .
Thank you for reporting.