Как создать обычный текст в Sphinx и DocString

Я добавил автодокументирование Sphinx в свой ванильный проект Django.

В ванильном проекте 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, чтобы он просто отображал текст как есть (просто очень длинное описание) и не обрабатывал его?

Полагаю, что нет возможности просто иметь текст как есть.

Для тех, кто пришел из 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'))
"""

Спасибо за подтверждение того, что нет другого, более простого способа избежать предупреждений.

Понятие "обычный" текст, или "простой", или "как есть", плохо определено. Текст - это, если хотите, довольно абстрактное понятие. Давайте подумаем об этом... Даже когда мы пишем что-то от руки, текст переводится на страницу. Текстовый редактор тоже обрабатывает вводимый текст: Он обычно отображает его моноширинным шрифтом, может применять подсветку синтаксиса, сохраняет явные переносы строк или мягко оборачивает абзацы. Текстовые процессоры делают еще больше. Как и браузер.

Sphinx также обрабатывает текст, но выполняет только промежуточный шаг. В конечном итоге он передает свой вывод на внутренний модуль рендеринга, такой как браузер для документации HTML или LaTeX, а затем, в конечном итоге, на программу просмотра PDF.

Мы можем сказать Sphinx не делать никакой обработки, благодаря директиве raw. Но результат в этом случае будет не очень привлекательным. Мы можем скопировать эту doc-строку из вопроса, вставить ее во вновь созданный файл и открыть этот файл в браузере. Он будет выглядеть ужасно, примерно так:

Конфигурация URL Список `urlpatterns` маршрутизирует URL в представления. Для получения дополнительной информации смотрите: httrs://docs.djangoproject.com/en/3.1/topics/http/urls/ Примеры: Функция views 1. Добавьте импорт: from my_app import views 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, просто чтобы не менять свои doc-строки. Sphinx предоставляет событие autodoc-process-docstring для облегчения этой задачи. Но в конечном итоге это оказалось слишком сложно, и теперь я просто использую Markdown для doc-строк. В Markdown, конечно, тоже есть некоторые правила, например, для списков. Но они обычно меньше мешают моему эстетическому восприятию.

Вернуться на верх