CODEWITHSUNDEEP
pythondjangopython-sphinxrestructuredtext
Zhao Li
Zhao Li

Reputation: 5716

How to create regular text in Sphinx and DocString

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?

Upvotes: 1

Views: 992

Answers (2)

john-hen
john-hen

Reputation: 4866

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.

Upvotes: 1

Zhao Li
Zhao Li

Reputation: 5716

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.

Upvotes: 0

Related Questions