sphinx-doc / sphinx-doc/sphinx
Add :caption: for .. doctest::
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
I wrote 1307 pages long book on Python (http://python.astrotech.io) using Sphinx and I love this tool. This is also not my first book using it.
Now the book is too long to check all 2767 "code-block" directives manually. I wanted to use sphinx.ext.doctest and CI process for this. The idea is super good, but doctest directive does not support neither caption, name nor emphasize-lines option. I can live without emphasizing, but I use caption all over the place to explain code.
https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/doctest.py#L165
https://github.com/sphinx-doc/sphinx/blob/master/sphinx/directives/code.py#L177
https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html#directives
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
Start in sphinx/ext/doctest.py around line 165 and compare the option handling in sphinx/directives/code.py around line 177. Read the doctest directive documentation at the linked page, then verify that :caption: is accepted and documented for .. doctest:: while existing behavior remains intact.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100