标签: python-sphinx

我尝试打开 Sphinx 的挑剔模式 (-n) 来捕获我可能意外创建的任何损坏的链接。但是，它会在我记录类型的所有位置发出错误。在某些情况下，我已经从语义上描述了类型（例如“3D 数组”），但它甚至对于从类型提示中提取的类型也是如此（即使将 intersphinx 设置为提取 Python 类型）。例如，对于这个模块

from typing import Callable

def foo(x: Callable[..., int]):
    pass

我得到了错误docstring of myproj.foo:: WARNING: py:class reference target not found: Callable[..., int]。这仅包含sphinx.ext.autodoc扩展sphinx.ext.intersphinx和新生成的conf.py。

有没有某种方法可以阻止 Sphinx 尝试生成类型信息的链接，或者至少阻止它在它们不存在时抱怨，同时仍然告诉我手写文档中的错误链接？

我正在使用 Sphinx 3.0.3。

MyST允许以 markdown 格式编写 sphinx 文档。是否可以将其与替换结合起来？

尝试使用 Sphinx 生成文档。

第一次使用：sphinx-apidoc 然后使用：sphinx-build html

我收到了有关该文件的警告modules.rst。文件存在，html 也生成了，它看起来绝对像一个目录。

index.rst我阅读了我能找到的有关该主题的所有主题，但没有解决问题（使用指令正确定位文件中的模块声明.. include::...）

我不知道该怎么做才能让它发挥作用

这是我的文件的副本index.rst，也许您会看到我看不到的东西。生成的第一个文件位于sources文件夹中

Welcome to documentation!
=====================================
    
.. toctree::
   :maxdepth: 4
   :caption: Contents:

   modules

   
Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

我也收到这样的消息：

..\doc\sphinx\index.rst:4: WARNING: toctree contains reference to nonexisting document u'modules'

如果我用另一个文档替换模块，我会得到以下信息：

\doc\sphinx\index.rst:4: WARNING: toctree contains reference to nonexisting document u'opsimtest'
looking for now-outdated files... none found
pickling environment... done
checking consistency... \doc\sphinx\_apidocs\modules.rst: WARNING: document isn't included …

使用sphinx_rtd_theme主题构建 Sphinx 网站时，如何View page source用链接替换文档页面顶部的超链接？Edit on GitHub

我正在使用 GitHub Pages手动构建类似readthedocs.io的网站，但所有文档页面右上角的链接仍然显示“查看页面源代码”而不是“在 GitHub 上编辑”。

该主题的文档列出了一些相关选项（display_github、vcs_pageview_mode和github_url），但没有提供示例。我尝试将它们设置在根目录中conf.py，但html_theme_options没有成功。

如何告诉sphinx_rtd_theme主题将View page source链接更改为Edit on GitHub我所有文档页面上的链接？

只需通过 即可添加文件链接:download:`Name <doc/name.pdf>`。

是否可以对目录执行相同的操作？天真的:download:`Dir <doc/>`不行

是否应该始终预先存档？

我正在使用带有扩展名的 Sphinx 自动生成 Python 包的文档autodoc。我面临的问题是跳过autodoc任何带有下划线的模块。

有些模块被强调，以阻止用户导入它们。但是，这些带下划线的文件中的类没有下划线。

当我手动将带下划线的模块添加到package_name.rst并运行时make html，它会显示。所以我的问题是如何从autodoc.

我试图避免package_name.rst通过脚本解析来添加它们。我希望有一个 autodoc 标志或 hack！

我们使用 Sphinx 构建 Python 文档，然后存储工件。然后，GitHub 直接在 CI 中显示一个链接以打开index.html.

但是，在构建 Sphinx 文档时，会创建数千个文件，这会减慢工件的上传速度。为了减少上传时间，我可以从doc上传压缩文件夹。那么，如何保存未压缩的文件夹呢？这是必需的，因为我们有一个文件artifact_path需要index.html. 或者还有其他方法可以解决这个问题吗？

- store_artifacts:
    path: folder.tar  # untar after?

免责声明：这是针对 SciPy 的，我是一名核心开发人员。这将非常有帮助，因为它花费了该管道大约 30% 的构建时间。

鉴于模块中的以下函数，mymodule我想使用 Sphinx 进行记录autodoc：

from typing import Union\nfrom collections.abc import Iterable\nfrom numpy.typing import ArrayLike\n\ndef foo(a: Union[str, int], b: Iterable, c: ArrayLike) -> None:\n    """Do something useful."""\n    pass\n

在源代码中，函数的签名非常可读。但是，在生成的文档中autodoc但是，在签名

\n

khadl._util.foo（a：Union [str，int]，b：collections.abc.Iterable，c：Union [int，float，complex，str，字节，numpy.generic，Sequence [Union [int，float，complex] , str, bytes, numpy.generic]], 序列[序列[任意]], numpy.typing._array_like._SupportsArray]) \xe2\x86\x92 无

\n

这是不可读的。源自模块的类typing以简短形式显示（Union, Sequence, Any），但对于抽象基类，Iterable会生成唯一标识符（collections.abc.Iterable），ArrayLike甚至“解包”（Union[int, float, complex, str, bytes, numpy.generic, Sequence[Union[int, float, complex, str, bytes, numpy.generic]], Sequence[Sequence[Any]], …

我不知道如何为Raises. 见下文。有可能吗？我得到的是一个要点RuntimeError（同样适用于ValueError）。\n例如：

   Raises:      \xe2\x80\xa2 RuntimeError -\n                     \xe2\x97\xa6 case1: when x happens * case 2: when y happens\n                \xe2\x80\xa2 ValueError -\n                     \xe2\x97\xa6 a is not all lowercase * current day is Sunday\n

class A\n    def f1(self, a: str):\n        """f1\n\n        Parameters\n        ----------\n        a: str\n            a\n\n        Raises\n        ------\n        RuntimeError\n            * case 1: when x happens\n            * case 2: when y happens\n\n        ValueError\n            * ``a`` is not all lowercase\n            * current day is Sunday\n        """\n

我使用 Sphinx 为我的项目生成文档，扩展名为autosummary. 它生成一个表，其中包含我的模块名称及其摘要。

这是结果的图像：

然而，行太长，我们必须使用滑块来阅读整个描述。

我想包装描述文本，以摆脱滑块。我到处寻找，却一无所获。

我尝试将| xxxx或放入<br /> xxxx我的描述中，但没有成功。

先感谢您 ！