如何在reStructuredText文档中交叉引用索引项？
例如,我如何交叉引用SectionB:
.. index::
pair: SectionA; SectionB
SectionB
--------
SectionB description.
我试着用:ref:'SectionB'和:index:'SectionB',但他们没有工作.
谢谢.
我目前正在将所有现有(不完整)文档迁移到Sphinx.
问题是文档使用Python文档字符串(模块是用C编写的,但可能无关紧要),并且必须将类文档转换为可用于Sphinx的表单.
有sphinx.ext.autodoc,但它会自动将当前文档字符串放到文档中.我想基于当前的文档字符串在(RST)中生成源文件,然后我可以手动编辑和改进.
你会如何将文档字符串转换为Sphinx的RST？
我希望能够在Python中解析基于sphinx的rst进行进一步处理和检查.就像是:
import sphinx
p = sphinx.parse("/path/to/file.rst")
do_something_with(p)
似乎在使用docutils.core.publish_file的docutils中可以实现某些功能:
publish_file(open("/path/to/file.rst")
但是,这对sphinx特定指令等一无所知......
我想使用sphinx构建我们的文档,并获得与NumPy文档相同的参数格式(https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt)
我发现有两种方法可以用sphinx记录第一种样式的参数,其中一种是
:param name: description
要么
:keyword name: description
和另一个(这是NumPy风格)
Parameters
----------
name: type
description
以下是一个示例:
http://docs.scipy.org/doc/numpy/reference/distutils.html#module-numpy.distutils
和来源
def get_subpackage(self,subpackage_name,
subpackage_path=None,
parent_name=None,
caller_level = 1):
"""Return list of subpackage configurations.
Parameters
----------
subpackage_name: str,None
Name of the subpackage to get the configuration. '*' in
subpackage_name is handled as a wildcard.
subpackage_path: str
If None, then the path is assumed to be the local path plus the
subpackage_name. If a setup.py file is not found in the
subpackage_path, then …我有一大堆使用标准 Sphinx.rst文件编写的 Python 包文档。我还对我的包进行了测试，其中我想包括一个测试，以确定文档是否可以正确编译为预期的输出。基本上，当我使用无处链接或标题格式不佳等时，我想捕获案例。
现在我知道我总是可以编写一个调用make html和测试退出代码的测试，但这感觉真的很脏，所以我认为必须有更好的方法。有人知道这是什么吗？
在我的conf.py中它说我应该看到内置主题列表的文档.现在我的第一个谷歌热门引导我到http://www.sphinx-doc.org/en/stable/theming.html#builtin-themes.那里有一堆主题,我的狮身人面像不知道.例如'经典'.
在conf.py
html_theme = 'classic'
在我的shell上我做: sphinx-build -b html source build
writing output... [100%] index
Exception occurred:
File "~\appdata\local\programs\python\python35\lib\site-packages\sphinx\jinja2glue.py", line 200, in get_source
raise TemplateNotFound(template)
jinja2.exceptions.TemplateNotFound: about.html
sphinx版本:1.6.3.
我正在尝试使用 Sphinx 记录一个项目，但遇到了一个问题，即仅从文件夹中导入了一些模块。我的项目结构如下所示：
Project
|
|--Main
| |--Scripts
| __init__.py
| libsmop.py
| conv_table.py
| f_discrim.py
| recipes.py
| ...
当我尝试运行make html，libsmop并recipes没有任何问题都是进口的，但是conv_table并f_discrim得到以下错误：
WARNING: autodoc: failed to import module u'conv_table' from module u'Scripts'; the following exception was raised:No module named conv_table
我不认为这是我的配置文件，因为它在我运行时找到了所有文件，sphinx-apidoc -o _rst Main/Scripts并且我已经确认它们出现在结果Scripts.rst文件中。
为什么 autodoc 会找到一些模块而不是其他模块？
编辑：
conv_table.py是这种形式：
import re
import numpy as np
"""
conv_table dictionary at the bottom of this file maps …Sphinx 非常擅长链接到特定的 Python 对象。
例如，写
:func:`foo.bar`
将直接链接到bar中的函数foo.py。我想要相同的功能，但是我不希望创建可点击的链接，而是希望它是bar(), 的代码。
该.. code-block:: language指令要求您手动编写要添加的代码。但我想使用intersphinx链接到外部 Sphinx 项目中已存在的代码，而不是自己编写代码。:mod:、:func:、 和其他仅创建链接，实际上并不包含源代码。
还有，.. literalinclude:: filename但就我而言，我无法使用它，因为该函数来自 Sphinx 项目外部（它是使用 intersphinx 链接的，不是实际项目的一部分）。即使.. literalinclude:: filename可以以某种方式跨项目工作，我认为我仍然需要使用:lines:来过滤每个功能，这将是一个巨大的痛苦来跟踪。
如何通过名称空间路径引用函数/类并使用它将其源代码直接添加到 sphinx 第一个文件中？（不是可点击的链接，而是文字代码）。
我已经使用 Sphinx 为 Django 项目创建了文档，并html在执行make html命令后将文件夹的内容复制到docs/我的 repo 文件夹中并将其推送到 Github。之后，我将此docs/目录设置为Github Pages，现在它正在加载文档，但css不起作用，它只是带有任何样式的文档文本。
这是我的狮身人面像config.py：
import os
import sys
import django
sys.path.insert(0, os.path.abspath('..'))
os.environ['DJANGO_SETTINGS_MODULE'] = 'PROJECT_NAME.settings'
django.setup()
templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
html_theme = 'bizstyle'
html_static_path = ['_static']
BUILDDIR = '.'
这是来自 GitHub 页面的文档页面的链接：https : //arycloud.github.io/Tagging-Project-for-Machine-Learning-Natural-Language-Processing/
有什么问题？
我在交叉引用自定义指令生成的部分时遇到问题。
这是指令：
from docutils import nodes
from docutils.parsers import rst
class TestDirective(rst.Directive):
has_content = False
required_arguments = 1
option_spec = {}
def run(self):
my_arg = self.arguments[0]
target_node = nodes.target('', '', refid=nodes.make_id(my_arg))
section = nodes.section(
'',
nodes.title(text=my_arg),
ids=[nodes.make_id(my_arg)],
names=[nodes.fully_normalize_name(my_arg)])
return [target_node, section]
def setup(app):
app.add_directive('mytest', TestDirective)
这是它的使用方法：
=============
Test document
=============
.. mytest:: section1
Section 1 content.
.. _section2:
section2
========
Section 2 content.
现在，以下仅适用于section2：
Here are links to :ref:`section1` and :ref:`section2`.
该链接仅正确生成section2，我收到以下错误：
test.rst:19: WARNING: undefined label: …