如何鏈接到根頁面中intersphinx

Question

我已經啓用了在我的項目sphinx.ext.intersphinx並增加了以下配置：

intersphinx_mapping = { 
    'python': ('https://docs.python.org/3', None), 
    'pyserial': ('https://pythonhosted.org/pyserial/', None), 
} 

在我有以下我index.rst：

This project depends on the :ref:`pyserial <pyserial:???>` library. 

我想鏈接指向http://pythonhosted.org/pyserial/，根URL爲intersphinx_mapping，但我不知道???應該是什麼。

如果我做:ref:`pyserial`或:ref:`pyserial <pyserial>`，我得到WARNING: undefined label: pyserial (if the link has no caption the label must precede a section header)

如果我做:ref:`pyserial <>`我得到WARNING: undefined label: (if the link has no caption the label must precede a section header)

我可以代替:ref:與`pyserial < http://pythonhosted.org/pyserial/>`_，但我真的想通過intersphinx引用頁面，以避免斷線。

我在Anaconda的Python 3.6.2上使用sphinx 1.6.3。我不是過度掛在我想鏈接的圖書館上。我懷疑答案不會與圖書館有關。

如果有任何問題，pyserial文檔的常規引用工作得很好。例如:py:class:`serial.Serial`鏈接到https://pythonhosted.org/pyserial/pyserial_api.html#serial.Serial。

Answer 1

您已滿足以下要求。這是最後一個令人沮喪的常見原因。

1. 將項目配置爲使用intersphinx。

2. 遠程文檔使用Sphinx，實際上有一個名爲objects.inv的庫存文件。當運行sphinx-build，日誌記錄應該是這樣的：

   loading intersphinx inventory from https://docs.python.org/3/objects.inv... 
   loading intersphinx inventory from https://pythonhosted.org/pyserial/objects.inv... 
   

3. 使用intersphinx Python項目的語法如下，就像任何cross-referencing link：

   你的情況

   :role_name:`title <target>` 
   

   所以：

   :ref:`pyserial <pyserial:reference-label-name>` 
   

4. 最後，對於給定頁面，某些期望的目標可能不存在於清單中。 This answer shows how to see all intersphinx targets，使用以下：

   python -m sphinx.ext.intersphinx 'https://pythonhosted.org/pyserial/objects.inv' 
   

   所有的API對象出現，這就是爲什麼你可以鏈接到這些，但只有其他對象的數量是有限的存在：

   std:label 
        examples         Examples        : examples.html#examples 
        genindex         Index         : genindex.html# 
        miniterm         serial.tools.miniterm     : tools.html#miniterm 
        modindex         Module Index       : py-modindex.html# 
        search         Search Page        : search.html# 
        urls          URL Handlers       : url_handlers.html#urls 
   

   缺乏任意標籤是作者常見的煩惱。

   您也可以check the project's reST source for targets，在這種情況下，沒有像.. _my-reference-label:這樣的參考標籤。

要解決此問題，您既可以使用任意的目標之一：

:ref:`pyserial <pyserial:genindex>` 

...或更好，但提交pull請求，你至少在提供標籤項目索引頁面，等待其接受，然後將其用於intersphinx鏈接。其他作者會讚賞它。

Answer 2

根據@StevePiercy的建議，我向pyserial提交了PR#261。由於PR已被接受，您現在可以使用welcome標籤鏈接到根文檔。像

This project depends on the :ref:`pyserial <pyserial:welcome>` library. 

另外要注意的事情是，pyserial文檔應該與https://pyserial.readthedocs.io/en/latest/，不https://pythonhosted.org/pyserial/因爲我一直在做。