El concepto de texto "normal", o "sin formato" o "tal cual", está mal definido. Pensemos en eso... Incluso cuando escribimos algo a mano, el texto se representa en la página. Un editor de texto también procesa su entrada: por lo general, la presenta en una fuente monoespaciada, puede aplicar resaltado de sintaxis y conservará saltos de línea explícitos o párrafos de ajuste suave. Los procesadores de texto hacen aún más. Al igual que un navegador. Sin una representación física, el texto en su forma más pura es bastante abstracto.

Sphinx también procesa texto, pero solo realiza un paso intermedio. Eventualmente entrega su salida a un back-end de renderizado, como el navegador para documentación HTML o LaTeX y luego, en última instancia, al visor de PDF.

Podemos decirle a Sphinx que no realice ningún procesamiento a través de la directiva raw formato. Pero el resultado en este caso no será muy atractivo. Si copiamos esa cadena de documentos de la pregunta, la pegamos en un archivo .html recién creado y abrimos ese archivo en el navegador, el resultado será ilegible:

Configuración de URL La lista `urlpatterns` enruta las URL a las vistas. Para obtener más información, consulte: httрs://docs.djangoproject.com/en/3.1/topics/http/urls/ Ejemplos: vistas de función 1. Agregue una importación: desde my_app vistas de importación 2. Agregue una URL a urlpatterns: ruta ( '', vistas.inicio, nombre='inicio') […]

Aquí es donde solemos ceder y alimentar a la Esfinge con lo que quiere: texto reEstructurado. Eso a menudo significa agregar líneas en blanco antes y después de los bloques, como listas .

Personalmente, nunca me gustó eso de reStructuredText. Se supone que es un "recargo mínimo", pero cada vez que quiero presentar una lista, así

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

no entenderá lo que quiero decir y tengo que agregar líneas adicionales, así:

 Here is a list: * item 1 * item 2 (and then the next paragraph)

Encuentro esto aún más molesto cuando se trata de ejemplos de código, que a menudo se sienten aún más intrínsecos a un párrafo. El espacio de pantalla vertical es un recurso valioso, particularmente para las cadenas de documentos, ya que están incrustadas en el código.

En el pasado, llegué a personalizar el procesamiento de Sphinx, haciendo que agregara las líneas en blanco automáticamente para no tener que cambiar mis cadenas de documentos. Sphinx proporciona el autodoc-process-docstring para facilitar eso. Pero, en última instancia, el análisis sintáctico y las mayúsculas y minúsculas fueron demasiado problemáticos y ahora solo estoy usando Markdown para las cadenas de documentos . Markdown también tiene algunas reglas de sintaxis, por supuesto. Pero las listas, por ejemplo, solo necesitan una línea en blanco después del último elemento, no antes del primero. Así que Markdown interfiere menos con mi sensibilidad estética para... bueno, cadenas de documentos de "texto sin formato".

Supongo que no hay forma de tener el texto tal como está.

Para cualquiera que venga de Markdown y no esté muy acostumbrado a Sphinx y DocStrings, así es como se deben agregar las líneas adicionales:

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

Gracias por la confirmación de que no hay otra manera más fácil de evitar las advertencias.