This patch introduces obvious visual cues about the parent-member
relationship through indentation.
This also changes the output by removing the parent out of
'parent.member' declarations which was previously necessary to create
meaningful cross reference tags. This capability is now replaced by
Sphinx's automagic resolution of nested members which fortunately
doesn't change the cross referencing semantics. So the changes are
cosmetic in nature.
In spite of these being cosmetic changes, they will be intrinsic
dependencies of the recursive parsing introduced later in this series.
Namely, with further nesting levels, this is used for trivially scaling
the original parent-member scoping.
---
hawkmoth/hawkmoth.py | 10 ++++------
hawkmoth/util/docstr.py | 8 +++-----
test/enum.stdout | 8 ++++----
test/example-40-enum.stdout | 8 ++++----
test/example-50-struct.stdout | 8 ++++----
test/struct.stdout | 8 ++++----
test/typedef-enum.stdout | 8 ++++----
test/typedef-struct.stdout | 8 ++++----
test/union.stdout | 12 ++++++------
9 files changed, 37 insertions(+), 41 deletions(-)
diff --git a/hawkmoth/hawkmoth.py b/hawkmoth/hawkmoth.py
index d7286a9..7b610dd 100755
--- a/hawkmoth/hawkmoth.py
+++ b/hawkmoth/hawkmoth.py
@@ -235,18 +235,15 @@ def parse(filename, **options):
# FIXME: this is sooo ugly, handles unnamed vs. named structs
# in typedefs
- parent = cursor.spelling
- if parent == '':
- parent = cursor.type.spelling
# FIXME: do this recursively and smartly
fmt = docstr.Type.MEMBER
name = c.spelling
ttype = c.type.spelling
- doc = docstr.generate(text=text, fmt=fmt, parent=parent,
- name=name, ttype=ttype,
- args=args, transform=compat)
+ doc = docstr.generate(text=text, fmt=fmt, name=name,
+ ttype=ttype, args=args, transform=compat)
+ doc = docstr.nest(doc, 1)
meta = {
'line': comment.extent.start.line,
@@ -271,6 +268,7 @@ def parse(filename, **options):
doc = docstr.generate(text=text, fmt=fmt, name=name,
ttype=ttype, args=args, transform=compat)
+ doc = docstr.nest(doc, 1)
meta = {
'line': comment.extent.start.line,
diff --git a/hawkmoth/util/docstr.py b/hawkmoth/util/docstr.py
index 4886e8f..27a631d 100644
--- a/hawkmoth/util/docstr.py
+++ b/hawkmoth/util/docstr.py
@@ -32,7 +32,7 @@ class Type(Enum):
Type.VAR: (1, '\n.. c:var:: {ttype} {name}\n\n{text}\n'),
Type.TYPE: (1, '\n.. c:type:: {name}\n\n{text}\n'),
Type.ENUM_VAL: (1, '\n.. c:macro:: {name}\n\n{text}\n'),
- Type.MEMBER: (1, '\n.. c:member:: {ttype}
{parent}.{name}\n\n{text}\n'),
+ Type.MEMBER: (1, '\n.. c:member:: {ttype} {name}\n\n{text}\n'),
Type.MACRO: (1, '\n.. c:macro:: {name}\n\n{text}\n'),
Type.MACRO_FUNC: (1, '\n.. c:function:: {name}({args})\n\n{text}\n'),
Type.FUNC: (1, '\n.. c:function:: {ttype}
{name}({args})\n\n{text}\n')
@@ -67,7 +67,7 @@ def nest(text, nest):
"""
return re.sub('(?m)^(?!$)', ' ' * nest, text)
-def generate(text, fmt=Type.TEXT, parent=None, name=None,
+def generate(text, fmt=Type.TEXT, name=None,
ttype=None, args=None, transform=None):
"""
Generate reST documentation string.
@@ -76,7 +76,6 @@ def generate(text, fmt=Type.TEXT, parent=None, name=None,
text (str): Documentation body.
fmt (enum :py:class:`Type`): Format type to use. Different formats
require different arguments and ignores others if given.
- parent (str): Name of the token's parent.
name (str): Name of the documented token.
ttype (str): Type of the documented token.
args (list): List of arguments (str).
@@ -99,5 +98,4 @@ def generate(text, fmt=Type.TEXT, parent=None, name=None,
(text_indent, fmt) = _doc_fmt[fmt]
text = nest(text, text_indent)
- return fmt.format(text=text, parent=parent,
- name=name, ttype=ttype, args=args)
+ return fmt.format(text=text, name=name, ttype=ttype, args=args)
diff --git a/test/enum.stdout b/test/enum.stdout
index fa6e8fe..a7a8ced 100644
--- a/test/enum.stdout
+++ b/test/enum.stdout
@@ -4,12 +4,12 @@
Enum doc.
-.. c:macro:: bar
+ .. c:macro:: bar
- Enumeration comment.
+ Enumeration comment.
-.. c:macro:: baz
+ .. c:macro:: baz
- Another.
+ Another.
diff --git a/test/example-40-enum.stdout b/test/example-40-enum.stdout
index 834fb02..75000b3 100644
--- a/test/example-40-enum.stdout
+++ b/test/example-40-enum.stdout
@@ -4,12 +4,12 @@
Frobnication modes for :c:func:`frob`.
-.. c:macro:: MODE_PRIMARY
+ .. c:macro:: MODE_PRIMARY
- The primary frobnication mode.
+ The primary frobnication mode.
-.. c:macro:: MODE_SECONDARY
+ .. c:macro:: MODE_SECONDARY
- The secondary frobnication mode.
+ The secondary frobnication mode.
diff --git a/test/example-50-struct.stdout b/test/example-50-struct.stdout
index 4399019..2eff861 100644
--- a/test/example-50-struct.stdout
+++ b/test/example-50-struct.stdout
@@ -4,12 +4,12 @@
Linked list node.
-.. c:member:: struct list * list.next
+ .. c:member:: struct list * next
- Next node.
+ Next node.
-.. c:member:: int list.data
+ .. c:member:: int data
- Data.
+ Data.
diff --git a/test/struct.stdout b/test/struct.stdout
index 1c32b59..1a0fa60 100644
--- a/test/struct.stdout
+++ b/test/struct.stdout
@@ -6,12 +6,12 @@
Woohoo.
-.. c:member:: int sample_struct.jesh
+ .. c:member:: int jesh
- member
+ member
-.. c:member:: struct sample_struct * sample_struct.next
+ .. c:member:: struct sample_struct * next
- foo next
+ foo next
diff --git a/test/typedef-enum.stdout b/test/typedef-enum.stdout
index 9bbb62a..44ef1a2 100644
--- a/test/typedef-enum.stdout
+++ b/test/typedef-enum.stdout
@@ -4,9 +4,9 @@
named typedeffed enum
-.. c:macro:: damn
+ .. c:macro:: damn
- named enumeration
+ named enumeration
.. c:type:: unnamed_t
@@ -14,7 +14,7 @@
unnamed typedeffed enum
-.. c:macro:: shit
+ .. c:macro:: shit
- unnamed enumeration
+ unnamed enumeration
diff --git a/test/typedef-struct.stdout b/test/typedef-struct.stdout
index 41c414f..bb46f1f 100644
--- a/test/typedef-struct.stdout
+++ b/test/typedef-struct.stdout
@@ -4,9 +4,9 @@
named typedeffed struct
-.. c:member:: int named.m
+ .. c:member:: int m
- named member
+ named member
.. c:type:: typedef_struct
@@ -14,7 +14,7 @@
unnamed typedeffed struct
-.. c:member:: int typedef_struct.m
+ .. c:member:: int m
- unnamed member
+ unnamed member
diff --git a/test/union.stdout b/test/union.stdout
index 40e1b95..8298e1f 100644
--- a/test/union.stdout
+++ b/test/union.stdout
@@ -4,17 +4,17 @@
Union documentation.
-.. c:member:: int foo.foo
+ .. c:member:: int foo
- int member 1.
+ int member 1.
-.. c:member:: int foo.bar
+ .. c:member:: int bar
- int member 2.
+ int member 2.
-.. c:member:: struct _baz foo._baz
+ .. c:member:: struct _baz _baz
- struct member.
+ struct member.
--
2.20.1
