|
@@ -26,6 +26,7 @@
|
|
|
|
|
|
import os
|
|
import os
|
|
import re
|
|
import re
|
|
|
|
+import textwrap
|
|
|
|
|
|
from docutils import nodes
|
|
from docutils import nodes
|
|
from docutils.parsers.rst import Directive, directives
|
|
from docutils.parsers.rst import Directive, directives
|
|
@@ -53,6 +54,19 @@
|
|
__version__ = "1.0"
|
|
__version__ = "1.0"
|
|
|
|
|
|
|
|
|
|
|
|
+def dedent(text: str) -> str:
|
|
|
|
+ # Adjust indentation to make description text parse as paragraph.
|
|
|
|
+
|
|
|
|
+ lines = text.splitlines(True)
|
|
|
|
+ if re.match(r"\s+", lines[0]):
|
|
|
|
+ # First line is indented; description started on the line after
|
|
|
|
+ # the name. dedent the whole block.
|
|
|
|
+ return textwrap.dedent(text)
|
|
|
|
+
|
|
|
|
+ # Descr started on same line. Dedent line 2+.
|
|
|
|
+ return lines[0] + textwrap.dedent("".join(lines[1:]))
|
|
|
|
+
|
|
|
|
+
|
|
# Disable black auto-formatter until re-enabled:
|
|
# Disable black auto-formatter until re-enabled:
|
|
# fmt: off
|
|
# fmt: off
|
|
|
|
|
|
@@ -164,7 +178,7 @@ def _nodes_for_members(self, doc, what, base=None, branches=None):
|
|
term = self._nodes_for_one_member(section.member)
|
|
term = self._nodes_for_one_member(section.member)
|
|
# TODO drop fallbacks when undocumented members are outlawed
|
|
# TODO drop fallbacks when undocumented members are outlawed
|
|
if section.text:
|
|
if section.text:
|
|
- defn = section.text
|
|
|
|
|
|
+ defn = dedent(section.text)
|
|
else:
|
|
else:
|
|
defn = [nodes.Text('Not documented')]
|
|
defn = [nodes.Text('Not documented')]
|
|
|
|
|
|
@@ -202,7 +216,7 @@ def _nodes_for_enum_values(self, doc):
|
|
termtext.extend(self._nodes_for_ifcond(section.member.ifcond))
|
|
termtext.extend(self._nodes_for_ifcond(section.member.ifcond))
|
|
# TODO drop fallbacks when undocumented members are outlawed
|
|
# TODO drop fallbacks when undocumented members are outlawed
|
|
if section.text:
|
|
if section.text:
|
|
- defn = section.text
|
|
|
|
|
|
+ defn = dedent(section.text)
|
|
else:
|
|
else:
|
|
defn = [nodes.Text('Not documented')]
|
|
defn = [nodes.Text('Not documented')]
|
|
|
|
|
|
@@ -237,7 +251,7 @@ def _nodes_for_features(self, doc):
|
|
dlnode = nodes.definition_list()
|
|
dlnode = nodes.definition_list()
|
|
for section in doc.features.values():
|
|
for section in doc.features.values():
|
|
dlnode += self._make_dlitem(
|
|
dlnode += self._make_dlitem(
|
|
- [nodes.literal('', section.member.name)], section.text)
|
|
|
|
|
|
+ [nodes.literal('', section.member.name)], dedent(section.text))
|
|
seen_item = True
|
|
seen_item = True
|
|
|
|
|
|
if not seen_item:
|
|
if not seen_item:
|
|
@@ -260,9 +274,12 @@ def _nodes_for_sections(self, doc):
|
|
continue
|
|
continue
|
|
snode = self._make_section(section.tag)
|
|
snode = self._make_section(section.tag)
|
|
if section.tag and section.tag.startswith('Example'):
|
|
if section.tag and section.tag.startswith('Example'):
|
|
- snode += self._nodes_for_example(section.text)
|
|
|
|
|
|
+ snode += self._nodes_for_example(dedent(section.text))
|
|
else:
|
|
else:
|
|
- self._parse_text_into_node(section.text, snode)
|
|
|
|
|
|
+ self._parse_text_into_node(
|
|
|
|
+ dedent(section.text) if section.tag else section.text,
|
|
|
|
+ snode,
|
|
|
|
+ )
|
|
nodelist.append(snode)
|
|
nodelist.append(snode)
|
|
return nodelist
|
|
return nodelist
|
|
|
|
|