sphinx-doc / sphinx-doc/sphinx
Confusing behaviour with autosummary and multiple source_suffix entries.
Nobody has claimed this yet.
- 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.
- If something other than
'.rst'is the first entry (say'.myst'), thenautosummarywill generate a reStructuredText file with a.mystextension, which will then be interpreted differently and not parsed properly. - The docs suggest that
source_suffixshould be a regular dictionary, implying that order is not important, yetautosummarydepends 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
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
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