| 1 |
import unittest |
| 2 |
|
| 3 |
from django.contrib.admindocs.utils import ( |
| 4 |
docutils_is_available, |
| 5 |
parse_docstring, |
| 6 |
parse_rst, |
| 7 |
) |
| 8 |
from django.test.utils import captured_stderr |
| 9 |
|
| 10 |
from .tests import AdminDocsSimpleTestCase |
| 11 |
|
| 12 |
|
| 13 |
@unittest.skipUnless(docutils_is_available, "no docutils installed.") |
| 14 |
class TestUtils(AdminDocsSimpleTestCase): |
| 15 |
""" |
| 16 |
This __doc__ output is required for testing. I copied this example from |
| 17 |
`admindocs` documentation. (TITLE) |
| 18 |
|
| 19 |
Display an individual :model:`myapp.MyModel`. |
| 20 |
|
| 21 |
**Context** |
| 22 |
|
| 23 |
``RequestContext`` |
| 24 |
|
| 25 |
``mymodel`` |
| 26 |
An instance of :model:`myapp.MyModel`. |
| 27 |
|
| 28 |
**Template:** |
| 29 |
|
| 30 |
:template:`myapp/my_template.html` (DESCRIPTION) |
| 31 |
|
| 32 |
some_metadata: some data |
| 33 |
""" |
| 34 |
|
| 35 |
def setUp(self): |
| 36 |
self.docstring = self.__doc__ |
| 37 |
|
| 38 |
def test_parse_docstring(self): |
| 39 |
title, description, metadata = parse_docstring(self.docstring) |
| 40 |
docstring_title = ( |
| 41 |
"This __doc__ output is required for testing. I copied this example from\n" |
| 42 |
"`admindocs` documentation. (TITLE)" |
| 43 |
) |
| 44 |
docstring_description = ( |
| 45 |
"Display an individual :model:`myapp.MyModel`.\n\n" |
| 46 |
"**Context**\n\n``RequestContext``\n\n``mymodel``\n" |
| 47 |
" An instance of :model:`myapp.MyModel`.\n\n" |
| 48 |
"**Template:**\n\n:template:`myapp/my_template.html` " |
| 49 |
"(DESCRIPTION)" |
| 50 |
) |
| 51 |
self.assertEqual(title, docstring_title) |
| 52 |
self.assertEqual(description, docstring_description) |
| 53 |
self.assertEqual(metadata, {"some_metadata": "some data"}) |
| 54 |
|
| 55 |
def test_title_output(self): |
| 56 |
title, description, metadata = parse_docstring(self.docstring) |
| 57 |
title_output = parse_rst(title, "model", "model:admindocs") |
| 58 |
self.assertIn("TITLE", title_output) |
| 59 |
title_rendered = ( |
| 60 |
"<p>This __doc__ output is required for testing. I copied this " |
| 61 |
'example from\n<a class="reference external" ' |
| 62 |
'href="/admindocs/models/admindocs/">admindocs</a> documentation. ' |
| 63 |
"(TITLE)</p>\n" |
| 64 |
) |
| 65 |
self.assertHTMLEqual(title_output, title_rendered) |
| 66 |
|
| 67 |
def test_description_output(self): |
| 68 |
title, description, metadata = parse_docstring(self.docstring) |
| 69 |
description_output = parse_rst(description, "model", "model:admindocs") |
| 70 |
description_rendered = ( |
| 71 |
'<p>Display an individual <a class="reference external" ' |
| 72 |
'href="/admindocs/models/myapp.mymodel/">myapp.MyModel</a>.</p>\n' |
| 73 |
'<p><strong>Context</strong></p>\n<p><tt class="docutils literal">' |
| 74 |
'RequestContext</tt></p>\n<dl class="docutils">\n<dt><tt class="' |
| 75 |
'docutils literal">mymodel</tt></dt>\n<dd>An instance of <a class="' |
| 76 |
'reference external" href="/admindocs/models/myapp.mymodel/">' |
| 77 |
"myapp.MyModel</a>.</dd>\n</dl>\n<p><strong>Template:</strong></p>" |
| 78 |
'\n<p><a class="reference external" href="/admindocs/templates/' |
| 79 |
'myapp/my_template.html/">myapp/my_template.html</a> (DESCRIPTION)' |
| 80 |
"</p>\n" |
| 81 |
) |
| 82 |
self.assertHTMLEqual(description_output, description_rendered) |
| 83 |
|
| 84 |
def test_initial_header_level(self): |
| 85 |
header = "should be h3...\n\nHeader\n------\n" |
| 86 |
output = parse_rst(header, "header") |
| 87 |
self.assertIn("<h3>Header</h3>", output) |
| 88 |
|
| 89 |
def test_parse_rst(self): |
| 90 |
""" |
| 91 |
parse_rst() should use `cmsreference` as the default role. |
| 92 |
""" |
| 93 |
markup = '<p><a class="reference external" href="/admindocs/%s">title</a></p>\n' |
| 94 |
self.assertEqual(parse_rst("`title`", "model"), markup % "models/title/") |
| 95 |
self.assertEqual(parse_rst("`title`", "view"), markup % "views/title/") |
| 96 |
self.assertEqual(parse_rst("`title`", "template"), markup % "templates/title/") |
| 97 |
self.assertEqual(parse_rst("`title`", "filter"), markup % "filters/#title") |
| 98 |
self.assertEqual(parse_rst("`title`", "tag"), markup % "tags/#title") |
| 99 |
|
| 100 |
def test_parse_rst_with_docstring_no_leading_line_feed(self): |
| 101 |
title, body, _ = parse_docstring("firstline\n\n second line") |
| 102 |
with captured_stderr() as stderr: |
| 103 |
self.assertEqual(parse_rst(title, ""), "<p>firstline</p>\n") |
| 104 |
self.assertEqual(parse_rst(body, ""), "<p>second line</p>\n") |
| 105 |
self.assertEqual(stderr.getvalue(), "") |
| 106 |
|
| 107 |
def test_parse_rst_view_case_sensitive(self): |
| 108 |
source = ":view:`myapp.views.Index`" |
| 109 |
rendered = ( |
| 110 |
'<p><a class="reference external" ' |
| 111 |
'href="/admindocs/views/myapp.views.Index/">myapp.views.Index</a></p>' |
| 112 |
) |
| 113 |
self.assertHTMLEqual(parse_rst(source, "view"), rendered) |
| 114 |
|
| 115 |
def test_parse_rst_template_case_sensitive(self): |
| 116 |
source = ":template:`Index.html`" |
| 117 |
rendered = ( |
| 118 |
'<p><a class="reference external" href="/admindocs/templates/Index.html/">' |
| 119 |
"Index.html</a></p>" |
| 120 |
) |
| 121 |
self.assertHTMLEqual(parse_rst(source, "template"), rendered) |
| 122 |
|
| 123 |
def test_publish_parts(self): |
| 124 |
""" |
| 125 |
Django shouldn't break the default role for interpreted text |
| 126 |
when ``publish_parts`` is used directly, by setting it to |
| 127 |
``cmsreference`` (#6681). |
| 128 |
""" |
| 129 |
import docutils |
| 130 |
|
| 131 |
self.assertNotEqual( |
| 132 |
docutils.parsers.rst.roles.DEFAULT_INTERPRETED_ROLE, "cmsreference" |
| 133 |
) |
| 134 |
source = "reST, `interpreted text`, default role." |
| 135 |
markup = "<p>reST, <cite>interpreted text</cite>, default role.</p>\n" |
| 136 |
parts = docutils.core.publish_parts(source=source, writer_name="html4css1") |
| 137 |
self.assertEqual(parts["fragment"], markup) |