如何在 Sphinx 和 DocString 中创建常规文本

Question

我在我的普通 Django 项目中添加了 Sphinx 自动记录。

vanilla Django 项目有一个我想保留的 DocString：

"""URL Configuration

The `urlpatterns` list routes URLs to views. For more information please see:
    https://docs.djangoproject.com/en/3.1/topics/http/urls/
Examples:
Function views
    1. Add an import:  from my_app import views
    2. Add a URL to urlpatterns:  path('', views.home, name='home')
Class-based views
    1. Add an import:  from other_app.views import Home
    2. Add a URL to urlpatterns:  path('', Home.as_view(), name='home')
Including another URLconf
    1. Import the include() function: from django.urls import include, path
    2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
"""

但是，Sphinx 正在尝试处理它并给我这些错误：

/usr/src/app/porter/urls.py:docstring of porter.urls:5: WARNING: Definition list ends without a blank line; unexpected unindent.
/usr/src/app/porter/urls.py:docstring of porter.urls:7: WARNING: Unexpected indentation.
/usr/src/app/porter/urls.py:docstring of porter.urls:9: WARNING: Block quote ends without a blank line; unexpected unindent.

如何告诉 Sphinx 按原样呈现文本（只是很长的描述）而不处理它？

Answer 1

我想没有办法让文本保持原样。

对于来自 markdown 并且不太习惯 Sphinx 和 DocStrings 的任何人，这是需要添加额外行的方式：

"""porter URL Configuration

The `urlpatterns` list routes URLs to views. For more information please see:
    https://docs.djangoproject.com/en/3.1/topics/http/urls/

Examples:

Function views
    1. Add an import:  from my_app import views
    2. Add a URL to urlpatterns:  path('', views.home, name='home')
Class-based views
    1. Add an import:  from other_app.views import Home
    2. Add a URL to urlpatterns:  path('', Home.as_view(), name='home')
Including another URLconf
    1. Import the include() function: from django.urls import include, path
    2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
"""

感谢您确认没有其他更简单的方法来避免警告。

Answer 2

“常规”文本或“普通”或“原样”的概念定义不明确。让我们考虑一下……即使我们手写一些东西，文本也会呈现到页面上。文本编辑器也会处理它的输入：它通常以 monospaced 字体呈现它，可能会应用语法高亮显示，并且会保留明确的换行符或软换行段落。文字处理器做得更多。浏览器也是如此。没有物理表示，最纯粹形式的文本相当抽象。

Sphinx 也处理文本，但只执行中间步骤。它最终将其输出移交给渲染后端，例如用于 HTML 文档的浏览器，或 LaTeX，然后最终移交给 PDF 查看器。

我们可以告诉 Sphinx 不要通过 raw 指令进行任何处理。但这种情况下的结果不会很吸引人。如果我们从问题中复制该文档字符串，将其粘贴到新创建的 .html 文件中，然后在浏览器中打开该文件，结果将难以辨认：

URL Configuration The `urlpatterns` list routes URLs to views. For more information please see: httрs://docs.djangoproject.com/en/3.1/topics/http/urls/ Examples: Function views 1. Add an import: from my_app import views 2. Add a URL to urlpatterns: path('', views.home, name='home') […]

这是我们通常让步并向 Sphinx 提供它想要的东西的地方：reStructuredText。这通常意味着在块前后添加空行，例如 lists.

就个人而言，我从不喜欢 reStructuredText。本来应该是“最小加价”，但是每当我想引入一个列表时，就像这样

Here is a list:
* item 1
* item 2
(and maybe even continuing here)

它不会理解我的意思，我必须添加额外的行，例如：

Here is a list:

* item 1
* item 2

(and then the next paragraph)

当涉及到代码示例时，我发现这更令人讨厌，因为代码示例通常感觉更像是一个段落。竖屏 space 是一种宝贵的资源，尤其是对于嵌入代码中的文档字符串。

过去，我什至自定义 Sphinx 的处理，让它自动添加空行，这样我就不必更改我的文档字符串。 Sphinx 提供了autodoc-process-docstring event to facilitate that. But ultimately, the parsing and special-casing was too much trouble and now I'm just 。当然，Markdown 也有一些语法规则。但是列表，例如，只需要在最后一项之后有一个空行，而不是在第一项之前。所以 Markdown 对我的审美敏感性的干扰较小……好吧，“纯文本”文档字符串。

如何在 Sphinx 和 DocString 中创建常规文本

How to create regular text in Sphinx and DocString

python

django

python-sphinx

restructuredtext