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

Question

我在我的 vanilla 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

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

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

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

URL 配置 `urlpatterns` 列表将 URL 路由到视图。有关更多信息，请参阅：httрs://docs.djangoproject.com/en/3.1/topics/http/urls/ 示例：函数视图 1. 添加导入：from my_app 导入视图 2. 添加 URL 到 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)

当涉及到代码示例时，我发现这更令人讨厌，因为这些示例通常感觉更符合段落的本质。垂直屏幕空间是一种宝贵的资源，尤其是对于嵌入在代码中的文档字符串。

过去，我什至自定义 Sphinx 的处理，让它自动添加空行，这样我就不必更改我的文档字符串。 Sphinx 提供了autodoc-process-docstring 事件来促进这一点。但最终，解析和特殊大小写太麻烦了，现在我只是using Markdown for the doc-strings。当然，Markdown 也有一些语法规则。但是，例如，列表只需要在最后一项之后有一个空行，而不是在第一项之前。所以 Markdown 对我对……好吧，“纯文本”文档字符串的审美敏感度的影响较小。

Answer 2

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

对于来自 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'))
"""

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