The concept of "regular" text, or "plain" or "as is", is poorly defined. Let's think about that… Even when we write something by hand, text is rendered onto 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. Without a physical representation, text in its purest form is rather abstract.
Sphinx also processes text, but only performs an intermediate step. It eventually 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 to not do any processing by way of the raw directive. But the result in this case will not be very appealing. If we copy that doc-string from the question, paste it into a newly created .html file, and open that file in the browser, the result will be illegible:
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 is where we usually give in and feed the Sphinx what it wants: reStructuredText. That often means adding blank lines before and after blocks, such as lists.
Personally, 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)
it won't understand what I mean and I have to add extra lines, like that:
Here is a list:
* item 1
* item 2
(and then the next paragraph)
I find this even more annoying when it comes to code examples, which often feel even more intrinsic to a paragraph. Vertical screen space is a precious resource, particularly for doc-strings as they are embedded in the code.
In the past, I went so far as to customize Sphinx's processing, having it add the blank lines automatically just so that I don't have to change my doc-strings. Sphinx provides the autodoc-process-docstring event to facilitate that. But ultimately, the parsing and special-casing was too much trouble and now I'm just using Markdown for the doc-strings. Markdown also has some syntax rules, of course. But lists, for example, only need a blank line after the last item, not before the first. So Markdown interferes less with my aesthetic sensibility for… well, "plain-text" doc-strings.
