标签: python-sphinx

我正在尝试使用 Sphinx 来记录我的 Python 项目，但我正在努力解决该工具与 JavaDoc 等用于记录 API 的常用工具之间的差异。当然，我发现 Sphinx 比记录 API 有更多用途，但它似乎缺乏更简单的任务。

我已经设法找到如何让 Sphinx 了解您的包结构，这样您就不必手动将其复制到 ReST 文件中。我的下一个问题是：

是否可以包含 Sphinx 所有类的源链接？

当然，源代码的格式应该很好，但由于 Sphinx 使用 pygments，我认为这不是问题。

我广泛使用 Sphinx 来编写文档，并且对它感觉很舒服。

然而，我发现自己更多地使用 Javascript（前端）而不是 Python。

是否有任何插件或方法可以使用 Sphinx 从 JavaScript 代码注释中执行类似的 API 文档，就像使用 Python 文档字符串一样？

sphinx autoclass 指令生成的输出将 __init__ 的参数添加到类名的末尾。有什么办法告诉sphinx排除它们吗？我需要记录不应显式构造的类，因此 __init__ 参数是应从文档中省略的内部实现细节

我正在看这个网站。具体来说，来源。创建一个绘图（包含源代码！）似乎非常简单：

.. plot: somefile.py

但是，当我尝试时，狮身人面像对我大喊大叫。 "ERROR: Unknown directive type "plot". 所以问题是我如何向 sphinx 传授该plot指令？

我正在使用 sphinx 记录我的项目，并使用 sphinxcontrib.napoleon 扩展，它允许我使用谷歌风格的文档字符串。

这是我的项目中的一个函数

def nn_normalized_weight(normweight_fn, qaid2_nns, qreq_):
    """
    Weights nearest neighbors using the chosen function

    Args:
        normweight_fn (func): chosen weight function e.g. lnbnn
        qaid2_nns (dict): query descriptor nearest neighbors and distances. qaid -> (qfx2_nnx, qfx2_dist)
        qreq_ (QueryRequest): hyper-parameters

    Returns:
        tuple(dict, dict) : (qaid2_weight, qaid2_selnorms)

    Example:
        >>> from ibeis.model.hots.nn_weights import *
        >>> from ibeis.model.hots import nn_weights
        >>> ibs, daid_list, qaid_list, qaid2_nns, qreq_ = nn_weights.testdata_nn_weights()
        >>> qaid = qaid_list[0]
        >>> #----
        >>> normweight_fn = lnbnn_fn
        >>> tup1 = nn_weights.nn_normalized_weight(normweight_fn, …

我正在尝试编写链接到包其他部分中的某些类和方法的 Sphinx 文档字符串，但无法弄清楚如何构建这些链接或让它们根据需要显示。

我有

# a.py

from .b import *

class A(object):

    def func_one():
        """Does stuff using `func_two` from `B`."""
        some_b = B ...
        some_b.func_two()
        # ...

和

# b.py

class B(object):

    def func_two():
        # ...

我的包裹存放在哪里

my_package/
    a.py
    b.py

我希望 Sphinx 文档A.func_one显示为

使用func_two来自 的东西B。

并 包含指向func_two和 的链接B。

我尝试过方法和类的全名的各种组合，但似乎不起作用。我该如何实现这个目标？

我的第一个文件中有一个列表项，我想在其中放入文字块，但我无法让文字块正确结束。

这是我的第一个：

1. Item 1 (not literal)
2. Item 2::

    MyCode.example()

    Description of the code shown above (not literal)

我希望以开头的段落位于Description其上方的文字块之外，但仍然是列表项 #2 的一部分。我能想到的唯一解决方法是：

1. Item 1 (not literal)
2. Item 2:

    ::

        MyCode.example()

    Description of the code shown above (not literal)

这允许非文字文本返回到先前的缩进级别，使所有内容看起来都像我想要的那样。但是，我希望将其放在::列表项的第一行。

::是否可以以允许保留在列表项的第一行的方式显式结束文字块？

我制作了一个 sphinx 项目/文档（使用 alabaster 主题），左侧有一个固定的侧边栏（包含 TOC），但有太多内容无法在屏幕上显示。如何使该内容可滚动，同时仍允许右侧（正文）单独滚动？

我见过这个类似的问题，但只涉及您自己的网站，而不是 sphinx alabaster 主题文档。

Sphinx 中有多个指令可用于创建盒装文本，例如 ex.. note::或.. topic::，但它们都包含标题。是否可以创建没有标题的盒装文本？

我第一次尝试使用 Sphinx。我正在跑步sphinx-quickstart，但不明白被问到的第一个问题：

> Separate source and build directories (y/n) [n]: 

这是什么意思？这些目录是否分开有什么区别？我怎么知道选择哪一个？