sphinx-doc / sphinx-doc/sphinx
label system of math directive is confusable
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Problem
In reST world, usually, we have two ways to give a label to an arbitrary node which is generated by directive. The first way is hyperlink target. And another is :name: option.
For example, we can give a label to figures like following:
.. _figure1:
.. figure:: sphinx-logo.png
.. figure:: sphinx-logo.png
:name: figure2
Both are working fine. Off course, we can refer it using :ref: role.
But math directive is not. It also supports :name: option (it is an alias of :label: option). But :ref: role can't refer it.
In addition, the behavior of equation number is not same between :name: option and hyperlink targets. With the option, the math_block has equation number automatically. On the other hand, putting hyperlink targets before math directive, the math_block does not have equation number.
Procedure to reproduce the problem
.. math:: E = mc^2
:name: equation1
.. _equation2:
.. math:: E = mc^2
Error logs / results
With :name: option, it is rendered as following:
\begin{equation}\label{equation:index:equation1}
\begin{split}E = mc^2\end{split}
\end{equation}
With a hyperlink target, it is rendered:
\phantomsection\label{\detokenize{index:equation2}}\begin{equation*}
\begin{split}E = mc^2\end{split}
\end{equation*}
Expected results
Both case are converted to same result.
Environment info
- OS: Mac
- Python version: 3.6.5
- Sphinx version: 1.7.4
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
Reproduce the two math directive cases and compare their :ref: behavior and rendered LaTeX output. Start from the math directive and its :name: or 🏷️ handling, then trace how hyperlink targets are processed. Done means both forms produce equivalent references and equation-number behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100