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

Question

我将 Sphinx 自动记录添加到我的 vanilla Django 项目中。

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

“常规”文本或“普通”或“原样”的概念定义不明确。 如果您愿意，文本是一个相当抽象的概念。 让我们考虑一下……即使我们手写内容，文本也会呈现到页面上。 文本编辑器也会处理它的输入：它通常以等宽字体呈现它，可以应用语法突出显示，并且将保留显式换行符或软换行段落。 文字处理器做得更多。 浏览器也是如此。

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

由于raw指令，我们可以告诉 Sphinx 不要做任何处理。 但这种情况下的结果不会很有吸引力。 我们可以从问题中复制该文档字符串，将其粘贴到新创建的文件中，然后在浏览器中打开该文件。 它看起来很糟糕，像这样：

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 作为输入。 这通常意味着在块之前和之后添加空行，例如列表。

我从不喜欢 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事件来促进这一点。 但最终这太麻烦了，现在我只是将 Markdown 用于 doc-strings 。 当然，Markdown 也有一些规则，比如对于列表。 但它们通常对我的审美敏感性的干扰较少。