readthedocs / readthedocs/sphinx-autoapi

Strange warning in autosummary when literal block notation is used in first line of docstring

Open
#327 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
494
Forks
147
Avg merge
9m
Merged PRs (30d)
1

Description

I noticed this warning when developing the docs in pyMOR. In the index.rst in pymor.algorithms/timestepping I get the warnings below. The warning originates in the docstring of the solve method.

/pymor/docs/source/autoapi/pymor/algorithms/timestepping/index.rst:71:<autosummary>:2: WARNING: Literal block expected; none found.
/pymor/docs/source/autoapi/pymor/algorithms/timestepping/index.rst:134:<autosummary>:2: WARNING: Literal block expected; none found.
/pymor/docs/source/autoapi/pymor/algorithms/timestepping/index.rst:191:<autosummary>:2: WARNING: Literal block expected; none found.

The problem is that autoapi tries to pick the first line of the docstring for the table and breaks if the first line of a valid docstring contains a literal block notation ::. This seems to be similar to an old issue in sphinx.

How to Reproduce
FROM python:3.9-slim

RUN apt update; apt install -y build-essential curl git unzip vim
RUN git clone https://github.com/pymor/pymor
WORKDIR /pymor
RUN pip install -e '.[full]'
RUN git fetch origin pull/1563/head:method-overview
RUN git checkout method-overview
RUN git revert --no-commit 3a4a17f13f206cac75d6fee30f76d2a0a57de46d..HEAD
RUN apt install -y python3-pyqt5
RUN sphinx-build -E docs/source docs/sphinx/
Your project

The docs in pyMOR.

OS

Linux

Python version

3.8, (3.7, 3.9)

Sphinx version

4.4.0

autoapi version

1.8.4

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the warning with the documented Docker setup and sphinx-build command, focusing on docs/source/autoapi/pymor/algorithms/timestepping/index.rst and the solve method docstring. Trace how autosummary selects the first docstring line when it contains ::; done means the documented build no longer emits the Literal block expected warning.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.