sphinx-doc / sphinx-doc/sphinx

Confusing behaviour with autosummary and multiple source_suffix entries.

Open
#9,891 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autosummary type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Describe the bug

It appears that the autosummary generates files with the first extension in source_suffix even though autosummary only generate reStructuredText. This is a problem when using multiple entries in source_suffix for several reasons.

  1. If something other than '.rst' is the first entry (say '.myst'), then autosummary will generate a reStructuredText file with a .myst extension, which will then be interpreted differently and not parsed properly.
  2. The docs suggest that source_suffix should be a regular dictionary, implying that order is not important, yet autosummary depends on the order. (I realize that for python > 3.7 dictionaries are ordered... but Sphinx currently supports 3.6+, so this is an implementation detail, not a language guarantee).

This is likely related to issue #2485, but the fix there does not seem to work in this case.

How to Reproduce
$ git clone https://github.com/mforbes/sphinx_issue_9891/
$ cd sphinx_issue_9891
$ pip install -r requirements.txt
$ make html
$ open _build/html/_generated/mymod.html
Expected behavior

Since autosummary currently only produces reStructuredText, it should always produce a ".rst" file or similar if that is included in source_suffix, otherwise a warning or error should be raised.

Your project

https://github.com/mforbes/sphinx_issue_9891/

Screenshots

This order works: mymod.html

source_suffix = {".rst": "restructuredtext", ".myst": "myst"}

This order fails: mymod.html because autosummary generates .myst files containing ReStructuredText, and then myst_parser picks these up and tries to interpret them as markdown.

source_suffix = {".myst": "myst", ".rst": "restructuredtext"}
OS

Mac OS X 10.14.6, but most likely cross platform

Python version

3.9

Sphinx version

4.2.0

Sphinx extensions

sphinx.ext.autosummary, myst_parser

Extra tools

make

Contributor guide

Open the contributing guide

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

Run the linked reproduction with the two source_suffix orderings and compare the generated autosummary output. Start by tracing autosummary's handling of source_suffix and the myst_parser/reStructuredText extensions. Done means generation is independent of dictionary order, or an appropriate warning or error is produced when .rst is unavailable.

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.