search

toolness / hive-django

A Django-based Hive website for member organizations, their employees, and other community members.
https://directory.hivelearningnetworks.org
1 stars 10 forks source link

admindocs won't support literal blocks immediately after the first paragraph of a docstring #1

Open toolness opened 10 years ago

toolness commented 10 years ago

In 43eea5b41d84ab70fb3c71e1d7d77aa11ff1cf18, I added a template filter with a docstring that was rendered as reStructuredText in admindocs, Django's automatic documentation generator.

However, the following docstring:

"""
Return the domain name of the given URL. For example::

    {{ 'http://example.org/stuff'|domainname }}

would display ``example.org``.
"""

Raises the error "Literal block expected; none found." on line 2 of the docstring in admindocs (the same error is also raised throughout django-crispy-forms' own docs). No amount of fiddling with things seemed to fix it, except for adding another paragraph at the beginning of the docstring, like so:

"""
Return the domain name of the given URL.

For example::

    {{ 'http://example.org/stuff'|domainname }}

would display ``example.org``.
"""

Debugging this was quite frustrating.

I'm not sure if the bug has something to do with my app's particular dependency configuration, or a bug in admindocs, docutils, or somewhere else entirely.

toolness commented 10 years ago

It's also possible that this is due to the fact that my development machine at the time was Windows, and it could be due to some weird CR/LF conversion issues.