标签: python-sphinx

我正在将 Sphinx 与 reStructuredText 结合使用。我可以使用反引号来创建内联文字，例如

This is an ``object``

=> 这是一个object.

但是，如果内联文字后面紧跟着一个字母，则反引号文本不会呈现为内联文字

They are ``object``s.

=> 它们是“对象”。

如何才能得到下面想要的渲染效果？

=> 他们是objects。

我有两个第一个文档，例如：

doc1.rst
doc2.rst

文档1.rst

Doc 1 content
*************

Foo bar
=======

baz !

文档2.rst

Doc 2 content
*************

You can see "foo bar" `here <doc1.html#foo-bar>`.

要在 doc2 中有一个到 doc1#foo-bar 的链接，我可以对其进行硬编码。但是如何在不进行硬编码的情况下实现呢？我可以用 sphinx 代码做到这一点吗？

any在使用 Sphinx 构建文档时，我将其用作默认角色，它按预期工作，自动链接一些标记的引用并将其他引用格式化为代码，同时避免标记使文档字符串混乱。

不幸的是，当以这种方式构建文档时，输出中充满了any无法找到目标的参考的警告：

WARNING: \'any\' reference target not found: [\xe2\x80\xa6]\n

有什么办法可以抑制这些警告吗？

到目前为止，我能以这种方式找到的唯一资源是这个问题，但是它具体涉及一个完全不同的警告。

我正在使用Sphinx版本1.4.5.

我的项目结构如下：

+ src > main.py + docs (generated with sphinx-quickstart)

src即使在添加文件夹路径后docs/conf.py：

sys.path.insert(0, os.path.abspath('../src'))

并使用以下命令生成src/main.py（即docs/src.rst和docs/modules.rst）的第一个文件：

$ sphinx-apidoc -fo docs src

当我尝试使用以下内容构建html网页时：

$ make clean
$ make html

它找不到模块src和src/main.py：

WARNING: autodoc: failed to import module u'src.main'; the following exception was raised

我有一个问题。如果我想将注释块放在代码块下的列表中，它就会包含在代码块中。如果我取消缩进，列表编号会在注释后重新开始。所以基本上，我需要的是：

Fixed list example
------------------

#. First do spam
#. Then do ``eggs``::

   some_code_stuff()

   .. note::

      Nobody expects the Spanish Inquisistion

#. Then do spam and ``eggs``.

该列表应在注释块之后以 3 继续。但目前，该..note块只是显示，就好像它是代码一样（由于之前的代码块）。有任何想法吗？

与以下内容有点相关：Sphinx：在注释部分后恢复列表编号

使用 Sphinx，可以在构建输出的 _static 文件夹中包含静态文件。如何将静态文件复制到构建文件夹的根目录？

背景：我在 Azure 应用服务中托管 Sphinx 项目的输出，并且由于几页中有 mp4 视频，我需要一个包含以下条目的“web.config”文件：

<staticContent>
    <mimeMap fileExtension=".mp4" mimeType="video/mp4" />
</staticContent>

我需要 Sphinx 将 web.config 包含在构建文件夹的根目录中。

我正在使用 Sphinx 默认主题在 Python 中创建文档agogo。

我想使用该topic指令在重要信息周围放置一个框，但 agogo 的 CSS 默认 CSS 中没有边框。我有 CSS 来创建边框，但如何包含/覆盖旧版本的 agogotopic以使用我的版本。

我希望能够生成文档，而无需每次手动更改 CSS。我研究了一些关于在 Sphinx 中使用自定义 CSS 的内容，但似乎没有提到覆盖现有的类。

我正在开发一个项目，我们可以生成 HTML 和 PDF 文档。

当表超过 30 行时，sp​​hinx 正确使用 Latex longtable 包。但是，对于较小的表，它使用 tabulary 包。

我的问题是我有一些表少于 30 行，但由于行很大，我需要分页符。

从我所有的阅读（具体来说，这里： https: //github.com/sphinx-doc/sphinx/issues/1898）看来，我应该简单地通过指定“：class：longtable”来强制sphinx使用longtable

不幸的是，我没有成功添加此规范，因为我的表没有使用单独的指令指定。

这是我的表的定义方式：

.. tabularcolumns:: |p{1cm}|p{4cm}|p{10cm}|

+--------+-----------------+--------------------------+
| Step # | Process Step(s) | Detail                   |
+========+=================+==========================+
| 1      | Testing         | Testing  Testing Testing |
+--------+-----------------+--------------------------+

我得到的所有在线示例都使用 list-tables 或 csv-tables，然后添加 longtable 命令作为相关指令的一部分。例如：

.. tabularcolumns:: |p{1cm}|p{7cm}|

.. csv-table:: Lorem Ipsum
   :file: _files/lorem-tab.csv
   :header-rows: 1
   :class: longtable

我已经尝试过这个，但不幸的是它不起作用：

.. tabularcolumns:: |p{1cm}|p{4cm}|p{10cm}|
   :class: longtable

+--------+-----------------+--------------------------+
| Step # | Process Step(s) | …

我正在尝试记录namedtuple。当我构建文档时，我WARNING: duplicate object description在记录的函数之后收到警告和相同的空函数。例如：

如何删除这些别名？我已经尝试过这个解决方案，编写了一些函数来conf.py创建空属性。

另外，我认为值得一提的是，构建后我得到了一个使用说明:noindex:，但我不明白应该在哪里使用它？在我的文档字符串、第一个文件或其他地方？

代码示例：

File = namedtuple("File", ["path", "size", "extension",
                           "adate", "mdate", "links",
                           "user_owner", "group_owner",
                           "inode", "device", "permissions",
                           "depth"])
"""File attributes.

.. py:attribute:: path

    **-** path to the found file

     .. note::
        depending on command-line arguments can be absolute or relative
...

我正在使用 Sphinx 的自动摘要为模块的每个成员自动生成单独的第一个文件。文档按预期创建，只是生成的第一个文件缺少除__init__.

在我的conf.py我有以下几行：

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
]

autosummary_generate = True
autosummary_imported_members = True

考虑下面的虚拟类，它包含 dunder 和常规公共方法：

class MyClassA:

    def __init__(self):
        r'__init__ docstring'
        pass

    def __call__(self):
        r'__call__ docstring'
        pass

    def __len__(self):
        r'__len__ docstring'
        pass

    def public_method_1(self):
        r'public_method_1 docstring'
        pass

    def public_method_2(self):
        r'public_method_2 docstring'
        pass

在我的第一个主文件中，我设置了自动摘要，如下所示：

.. autosummary::
    :toctree: my_module_members

    my_module.MyClassA
    my_module.MyClassB

/my_module_members正如预期的那样，自动摘要会为模块的每个成员创建一个以单独的第一个文件命名的子目录。但仅__init__在这些自动生成的第一个文件的“方法”部分中列出。例如：

my_module.MyClassA
==================

.. currentmodule:: my_module

.. autoclass:: MyClassA




   .. rubric:: Methods

   .. autosummary::

      ~MyClassA.__init__
      ~MyClassA.public_method_1
      ~MyClassA.public_method_2

因此，在生成的 html 文档中，方法表中仅列出了这三个方法，而没有 …