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

Question

I added Sphinx auto-documenting to my vanilla Django project.

The vanilla Django project has a DocString that I want to keep:

"""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'))
"""

However, Sphinx is trying to process it and gives me these errors:

/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.

How can I tell Sphinx to just render the text as-is (just a very long description) and don't process it?

Answer 1

I guess there's no way of just having the text as-is.

For anyone coming from markdown and not quite used to Sphinx and DocStrings, this is how the extra lines needed to be added in:

"""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'))
"""

Thank you for the confirmation that there's not other, easier way to avoid the warnings.

Answer 2

The concept of "regular" text, or "plain" or "as is", is poorly defined. Text is, if you will, a rather abstract concept. Let's think about that… Even when we write something by hand, text is rendered to the page. A text editor processes its input too: It usually renders it in a monospaced font, may apply syntax highlighting, and will either preserve explicit line breaks or soft-wrap paragraphs. Word processors do even more. As does a browser.

Sphinx also processes text, but only performs an intermediate step. It ultimately hands over its output to a rendering back-end, such as the browser for HTML documentation, or LaTeX and then ultimately the PDF viewer.

We can tell Sphinx not to do any processing, thanks to the raw directive. But the result in this case will not be very appealing. We can copy that doc-string from the question, paste it into a newly created file, and open that file in the browser. It will look terrible, something like this:

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') […]

This where we usually give in and give Sphinx what it wants: reStructuredText as input. That often means adding blank lines before and after blocks, such as lists .

I never liked that about reStructuredText. It's supposed to be "minimal mark-up", but whenever I want to introduce a list, like so

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

I have to add extra lines, like that:

Here is a list:

* item 1
* item 2

(and then the next paragraph)

In the past, I even went so far as to customize Sphinx's processing, just so that I don't have to change my doc-strings. Sphinx provides the autodoc-process-docstring event to facilitate that. But eventually that was too much trouble and now I'm just using Markdown for the doc-strings . Markdown also has some rules, of course, such as for lists. But they usually interfere less with my aesthetic sensibility.