search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.55k stars 2.12k forks source link

WARNING: undefined label :ref: tag can't generate HTML cross reference properlly for i18n documentation #1300

Closed shimizukawa closed 9 years ago

shimizukawa commented 9 years ago

The issue

I used :ref: tag but it seems that HTML cross references are not properlly generated.

but it seems that sphinx can't find label in Japanese documentation. It works for English documentation.

Here is the output results at that time.

pickling environment... done
checking consistency... /home/kenhys/work/sphinx/sphinx-missing-xref/doc/source/news.rst:: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [ 33%] index
writing output... [ 66%] install
writing output... [100%] news

/home/kenhys/work/sphinx/sphinx-missing-xref/doc/source/install.rst:23: WARNING: undefined label: release-1-20 (if the link has no caption the label must precede a section header)
/home/kenhys/work/sphinx/sphinx-missing-xref/doc/source/install.rst:25: WARNING: undefined label: release-2-00 (if the link has no caption the label must precede a section header)

Actual Result

doc/locale/ja/html/install.html shows:

<em class="xref std std-ref">release-1-20</em> を参照してください。

Expected Result

doc/locale/ja/html/install.html shows:

<a class="reference internal" href="news.html#release-1-02"><em>1.20リリース - 2012/01/29</em></a>

How to reproduce

I've attached archives which reproduced this situation.

This issue is found on Mroonga (http://mroonga.org) documentation. I try to minimize from original source, the directory structure may be strange for normal sphinx user.

Here is the tree of arvhives:

shimizukawa commented 9 years ago

From kenhys on 2013-10-30 09:36:20+00:00

Here is the summary of sphinx:

% hg summary
parent: 4359:e55c174b5dc5 
 Merged in minrk/sphinx/minrk/sort-inheritance-diagram (https://bitbucket.org/birkenfeld/sphinx/pull-request/183)
branch: default
commit: (clean)
update: (current)
shimizukawa commented 9 years ago

From Georg Brandl on 2014-01-19 11:13:26+00:00

I'm very confused. I reproduced this and I don't know why it happens for some targets and not for others.

shimizukawa commented 9 years ago

From Georg Brandl on 2014-01-19 14:22:12+00:00

Takayuki Shimizukawa OK, two debugging results:

shimizukawa commented 9 years ago

From Georg Brandl on 2014-01-19 14:39:08+00:00

Closes #1300: Fix references not working in translated documents in some instances.

→ <>

shimizukawa commented 9 years ago

From Georg Brandl on 2014-01-19 14:40:55+00:00

Found a solution for 1.2.1 which should not be too problematic:

the issue is 

                    # re-entry with new named section node.
                    self.document.note_implicit_target(section_node, section_node)

-- if the target name is duplicate this will insert a system_message node which gets the release-1-20 name somehow. I removed the second argument which suppresses the system_message.

Takayuki Shimizukawa If you think the message should stay maybe you can find a different way to emit it.

shimizukawa commented 9 years ago

From Takayuki Shimizukawa on 2014-08-30 07:25:40+00:00

Georg Brandl Thanks for the fixing! I confirmed the problem and investigating the cause too. I can say that your change is perfect. Just to make sure, I added a source comment.

shimizukawa commented 9 years ago

From Takayuki Shimizukawa on 2014-08-30 07:26:21+00:00

Add source comment to explain why is the second argument (msgnode) not needed. Refs #1300, 8d51df20d4

→ <<cset 45cfb42864c24bb1aad671bfdb8287877efac3e5>>