Debian Codegraph @

tests/admin_docs/test_utils.py

raw
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)