readthedocs / readthedocs/sphinx-autoapi
Strange warning in autosummary when literal block notation is used in first line of docstring
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
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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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