标签: python-sphinx

每次我都必须引用一个我不愿意引用的方法:func:`package.subpackage.module.method`，尤其是那些经常使用的方法。有没有办法以某种方式“注册”，package.subpackage这样就module.method足够了？（更好的是，假设没有冲突，package.subpackage.module这样就足够了）。method

解决方案不应涉及将目录添加到packageor subpackage，但我可以将任何内容添加到docs/. 请注意，这里的问题涉及method文档字符串模块外部的定义（否则.method有效）。

是否可以以任何方式插入指向 reStructuredText 文件中锚点的 Markdown 文件的链接？

我有一个项目文档，其中也包含 .rst 和 .md 文件，并且我正在使用m2rr Sphinx 扩展，但它似乎只支持文件内的 rst 锚链接。

有什么办法可以实现这一点吗？

我注意到 Sphinx 呈现类描述的行为发生了变化。鉴于此代码

# my example happens to be a dataclass, but the behavior for 
# regular classes is the same
@dataclass
class TestClass:
    """This is a test class for dataclasses.

    This is the body of the docstring description.
    """
    var_int: int
    var_str: str

加上一些通用的狮身人面像设置，我大约两年前就得到了这个

现在我得到了这个

有没有办法告诉 Sphinx 不要将类变量添加到类定义的底部？尤其令人烦恼的是，它假设它们的值为None，只是因为它们没有默认值。

这个问题是在这篇文章的讨论中出现的，其中还包含有关 Sphinx 配置等的评论中的更多上下文。

我正在尝试记录一个具有一些类级成员变量的 Python 类，但我无法使用 reST/Sphinx 对其进行适当记录。

代码是这样的：

class OSM:
    """Some blah and examples"""
    url = 'http://overpass-api.de/api/interpreter'  # URL of the Overpass API
    sleep_time = 10  # pause between successive queries when assembling OSM dataset

但我得到了这个输出（请参见绿色圆圈区域，我希望在其中有一些描述这两个变量的文本，如上所述）。

对于模糊之处，我深表歉意，但示例的一部分有些敏感

我创建了一个带有指令的网格表：

..table:: *Table 1: Power Connector* 
  :align: center

这是结果：

最大的问题是如何将标题“表 1：电源连接器”移动到表格下方，有什么技巧吗？我确信有，只是请不要深入研究 Sphinx 的源代码，给我一些简单的角色或可以做到这一点的东西（CSS 或其他东西），理想情况下，一个内置角色，如:align:

对于一款流行的文档软件来说，Sphinx确实缺乏很多高级的解释。:align:在对 Sphinx 本身的 python 源代码进行了一系列修改之前，我几乎没有找到该指令。拜托，Sphinx只是学习Python的借口吗？

我的文件中有一段代码，我想使用literalinclude指令将其包含在 Sphinx 文档的示例中。

但该代码位于一个函数中，因此当我包含它时，在示例中，每行缩进比我想要的多一级。

.. literalinclude:: ../../examples/example.py
   :language: python
   :lines: 13-42
   :tab-width: 0

生产

.. literalinclude:: ../../examples/example.py
   :language: python
   :lines: 13-42
   :tab-width: 0

还有其他方法可以删除或取消缩进文字块吗？

背景：我升级了我的存储库以使用 python 3.9（以前是 3.6）。将所有软件包升级到最新。注意到我的文档没有使用 sphinx-rtd-theme 进行格式化。请参阅https://docs.members.loutilities.com/en/1.4.1.dev1/与https://docs.members.loutilities.com/en/1.4.0/进行比较

使用 chrome 控制台查看了差异，在 1.4.0 中，格式化是通过https://docs.members.loutilities.com/en/1.4.0/_static/css/theme.css完成的，但是 theme.css 1.4.1.dev1 中缺少文件。

注意：恢复到旧的、之前工作的 rtd-requirements.txt 并不能解决问题。

回购代码位于https://github.com/louking/members/tree/1.4.1.dev1/docs

具体来说，conf.py 有以下内容

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to …

我注意到Sphinx能够使用JSON生成文档.这些文件用于什么？

我在reStructuredText中有以下整洁的小表:

======   =======   ======  =====================
Symbol   Meaning   Type    Example
======   =======   ======  =====================
   G     Era       Text    "GG" -> "AD"
   y     Year      Number  "yy" -> "03"
                           "yyyy" -> "2003"
   M     Month     Text    "M" -> "7"
                   or      "M" -> "12"
                   Number  "MM" -> "07"
                           "MMM" -> "Jul"
                           "MMMM" -> "December"
======   =======   ======  =====================

根据关于简单表的Docutils文档,我希望Spinx生成的HTML表格在文本中生成,因此"yy"和"yyyy"将在不同的行上,就像"M","MM" " 等等.但结果如下:

我尝试了一些替代方法,比如在最后一列的开头使用管道(|),空行,缩进.我最接近的是在"yyyy"之前使用缩进.然后"yyyy"在下一行,但它是缩进的.当然我希望它与"yy"处于相同的缩进级别.

我正在学习本教程,以便为我的Django项目生成文档.

我已经添加sys.path.append(os.path.join(os.path.dirname(__name__), '..'))到conf.py文档目录中的文件中.

但是运行make html一直给我这样的错误:

配置不正确:请求设置LOGGING_CONFIG,但未配置设置.您必须在访问设置之前定义环境变量DJANGO_SETTINGS_MODULE或调用settings.configure().

我的项目运行正常,所以我不确定我应该打电话到settings.configure()哪里？