Как создать обычный текст в 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, конечно, тоже есть некоторые правила, например, для списков. Но они обычно меньше мешают моему эстетическому восприятию.