标签: python-sphinx

在 python 模块中，在模块的文档字符串中我有以下内容：

:meth:`my_method`\n

我在当前模块中有以下课程：

class GameP:\n\n    ...\n\n    def my_method(self):\n        return f"{self._name} {self.selected}"\n

Sphinx 不会为此创建链接，但在 Sphinx 文档中我们有：

\n

通常，首先搜索这些角色中的名称，无需任何进一步的限定，然后在前面加上当前模块名称，然后在前面加上当前模块和类名称（如果有）。如果在名称前添加点，则此顺序相反。例如，在 Python\xe2\x80\x99s codecs127 模块的文档中，:py:func:open始终指内置函数，而 :py:func:.open指 codecs.open()。

\n

为什么粗体部分不适合我？:meth:角色没有为我建立链接。

我正在为一个包开发文档，当我构建 sphinx 文档时，我得到了双冒号

对于每个函数定义的所有字段。

我的文档字符串使用 numpydoc 样式，这些文档中没有冒号来指示它们可能来自哪里：

    """

    Function description

    Parameters
    -----------
    param1: str or list
        A description for the parameter

    Returns
    -----------
    Dictionary
        Some info about what is returned

    Examples
    -----------
        >>> output = somefunction(param1)

    """

以前有人遇到过这个吗？值得注意的是，这种情况不会发生在Examples现场。只是Parameters，，Returns和Return Type。

正如本文所述，即使 napoleon 将字段添加为文档，autodoc 也会急切地将类变量添加到文档中：

from dataclasses import dataclass
@dataclass
class Foo():
    """Some class

    Attributes:
        a: foo
        b: bar
    """
    a: str
    b: int

    def c(self) -> int:
        """Here's a doc'd function
        """
        return 3

我想明确告诉 autodoc 不要记录任何类变量（在数据类的情况下也是实例变量） - 我只希望 autodoc 显示给定类的声明函数并让 napoleon 处理它的所有类的类/实例变量发现. 这是否可以在没有:exclude-members:每堂课的情况下实现（这是一个巨大的麻烦）？

我已经尝试过：

autodoc_default_options = {
    'members':          True,
    'undoc-members':    False,
}

在我的conf.py文件中.rst：

.. automodule:: some.module
    :members:
    :show-inheritance:

这应该隐藏无证成员，但他们仍然出现：

在 Jupyter-book 中，我正在创建一个 _toc.yml 文件。我有类似的东西 -

- caption: Tutorials
  chapters:
  - file: ../../notebooks/some_notebook

我得到了例外 -

home/code/nwb_datajoint/docs/web-doc/intro.md:: WARNING: toctree contains reference to nonexisting document '../../notebooks/some_notebook' [etoc.ref]
looking for now-outdated files... none found

如何引用 _toc.yml 父目录中的相对目录？

我正在使用 Sphinx 为 python 项目构建文档并阅读文档。由于某种原因，代码块在构建文档后不会呈现，并且内联代码（用反引号标记）显示为斜体。我检查了原始版本，有一个警告，指出无法找到 exomagpy 模块，我通过将 conf.py 的 os.path.abspath() 部分中的“..”更改为“../”来解决该问题，这似乎没有改变文档中的任何内容。stackoverflow上有一个类似的问题，我尝试了解决方案，但它没有改变。

原始版本可以在这里找到：https ://readthedocs.org/api/v2/build/17574729.txt

这些文档是从 github 页面的“开发”分支构建的（链接如下）

以下是 github 页面的链接：https://github.com/quasoph/exomagpy/tree/Develop

回购协议的结构如下：

>.vscode
>build/lib/exomagpy

>docs
   >conf.py
   >rst files (.rst)
   >makefile
   >make.bat

>exomagpy.egg-info

>exomagpy
   >__init__.py
   >module files (.py)

>.readthedocs.yml
>requirements.txt
>setup.py

这是我的文件：

.conf.py

import os
import sys
sys.path.insert(0, os.path.abspath("../"))

# project info

project = "exomagpy"
root_doc = "index"
release = "1.3.0"

# general config

extensions = ["sphinx.ext.autodoc","sphinx.ext.napoleon","sphinx.ext.autosummary"
]

templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# html options …

我正在使用 Sphinx 生成 python 包的 API 文档。目前我收到警告

WARNING: duplicate object description of package.module.submodule.Class.function other instance in generated/package.module.submodule, use :noindex: for one of them

基本上每个函数都会产生 300 多个警告。

我的 RST 文件如下所示：

api.rst:

.. autosummary::
    :toctree: generated
    :recursive:
    :template: module-template.rst
    
    package

模块模板.rst：

{{ fullname | escape | underline}}

{% block modules %}
{% if modules %}
.. rubric:: {{ _('Submodules') }}

.. autosummary::
   :toctree:
   :template: module-template.rst
   :recursive:
   {% for item in modules %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% …

假设 sphinx 的文档结构如下：

doc
 |_ _static
 |_ _templates
 |_ api
     |_ index.rst
     |_ classes.rst
     |_ functions.rst
 |_ index.rst
 |_ more_functions.rst
 |_ conf.py

并且classes.rst，functions.rst并且more_functions.rst具有可以使用 来自动记录的类和函数autodoc/autosummary。构建将为.rst这些类和函数生成文件：

• doc/generated为了more_functions.rst
• doc/api/generated对于classes.rst和functions.rst

有没有办法控制这些generated文件夹的创建位置？

我试图generated最终获得一个独特的文件夹。在这种情况下，采用以下结构：

doc
 |_ generated
     |_ generated-from-more-functions.rst
     |_ api
         |_ generated-from-api/classes.rst
         |_ generated-from-api/functions-rst

我正在使用Sphinx来创建我的项目的文档.我想使用扩展名sphinx.ext.pngmath并使用这个小测试:

    Returns the indefinite integral of the polynomial *poly*:
    .. math::
        \int p(x)dx

我收到了错误:

WARNING: inline latex u'\\int p(x)dx\n\n': latex exited with error:             
[stderr]

[stdout]
This is pdfTeX, Version 3.1415926-1.40.10 (TeX Live 2009/Debian)
 restricted \write18 enabled.
entering extended mode
(./math.tex
LaTeX2e <2009/09/24>
Babel <v3.8l> and hyphenation patterns for english, usenglishmax, dumylang, noh
yphenation, loaded.
(/usr/share/texmf-texlive/tex/latex/base/article.cls
Document Class: article 2007/10/19 v1.4h Standard LaTeX document class
(/usr/share/texmf-texlive/tex/latex/base/size12.clo))
(/usr/share/texmf-texlive/tex/latex/base/inputenc.sty

! LaTeX Error: File `utf8x.def' not found.

Type X to …

import myModule as myModule

使用此代码工作导入,我可以使我的文档

import myPackage.myModule as myModule

有了这个我得到"没有名为myPackage.myModule的模块"无论这个文件是存在于根目录还是myPackage目录中.

在RST-File中我没有提到myModule,我想记录其他只导入该模块的文件.

我使用Sphinx和autosummary来生成Python软件的文档.它运行良好但生成的.rst文件还列出了导入的函数和类,这不是我想要的行为.

例如,带有docstring的包"packageex":

"""
Package Example (:mod:`packageex`)
==================================

.. currentmodule:: packageex
.. autosummary::
   :toctree:

   module0
   module1
"""

会产生一个文件packageex.module0.rst

Module0 (:mod:`packageex.module0`)
=================================

.. currentmodule:: packageex.module0

.. rubric:: Functions

.. autosummary::

   f0
   f1
   f2_imported
   f3_imported

.. rubric:: Classes

.. autosummary::

   Class0
   ClassImported

有没有办法只列出模块中定义的函数和类(而不是那些导入的函数和类)？

在autodoc文档(http://sphinx-doc.org/latest/ext/autodoc.html)中,"在一个自动模块指令中设置了成员选项集,只有模块成员的__module__属性等于模块名称为将记录给自动模块.这是为了防止导入的类或函数的文档.如果要防止此行为并记录所有可用成员,请设置imported-members选项.请注意,导入模块的属性将不会记录,因为属性通过解析当前模块的源文件来发现文档." 是否有可能通过autosummary获得相同的行为？