On Mon, 14 Dec 2020, Jani Nikula <jani@xxxxxxxxxx> wrote:
On Mon, 14 Sep 2020, Bruno Santos <brunomanuelsantos@xxxxxxxxxxxxxxxxxx>
wrote:
All the new domains are purely cosmetic changes, but some of them are
indeed nicer. We implement some of them here, leaving aside the
`c:enumerator::`. This one has no use case indications and as far as I
can see is simply an alias for the (also new) `c:enum::`.
Didn't test yet, but perhaps it could be used for the enumerator values
instead of our current macro?
This breaks compatibility with Sphinx 2 which does not provide any of
the new directives or, in the case of `c:macro::`, doesn't support the
new use cases.
Let's forget about Sphinx 2 and go Sphinx 3 all-in.
---
hawkmoth/parser.py | 9 +++++++--
hawkmoth/util/docstr.py | 10 ++++++++--
2 files changed, 15 insertions(+), 4 deletions(-)
diff --git a/hawkmoth/parser.py b/hawkmoth/parser.py
index 83b67c0..42e5576 100644
--- a/hawkmoth/parser.py
+++ b/hawkmoth/parser.py
@@ -1,5 +1,5 @@
# Copyright (c) 2016-2017 Jani Nikula <jani@xxxxxxxxxx>
-# Copyright (c) 2018-2019 Bruno Santos
<brunomanuelsantos@xxxxxxxxxxxxxxxxxx>
+# Copyright (c) 2018-2020 Bruno Santos
<brunomanuelsantos@xxxxxxxxxxxxxxxxxx>
# Licensed under the terms of BSD 2-Clause, see LICENSE for details.
"""
Documentation comment extractor
@@ -199,7 +199,12 @@ def _recursive_parse(comments, cursor, nest, compat):
# FIXME: Handle anonymous enumerators.
- fmt = docstr.Type.TYPE
+ fmts = {CursorKind.STRUCT_DECL: docstr.Type.STRUCT,
+ CursorKind.UNION_DECL: docstr.Type.UNION,
+ CursorKind.ENUM_DECL: docstr.Type.ENUM}
+
+ fmt = fmts[cursor.kind]
+
result = _result(comment, cursor=cursor, fmt=fmt,
nest=nest, name=ttype, compat=compat)
This produces
.. c:struct:: struct foo
.. c:union:: union foo
.. c:enum:: enum foo
However, apparently Sphinx expects just the name, without
struct/union/enum here.
'make test' doesn't reveal any problems, however 'make html' emits
obscure warnings that I discovered were caused by this. (Somehow we need
to figure out how to catch Sphinx warnings in 'make test' too!)
/hawkmoth/doc/examples/example-40-enum.c:2: WARNING: Invalid C declaration:
Expected identifier in nested name, got keyword: enum [error at 4]
enum mode
----^
/hawkmoth/doc/examples/example-50-struct.c:2: WARNING: Invalid C declaration:
Expected identifier in nested name, got keyword: struct [error at 6]
struct list
------^
I tried to fix this by using name=name for _result() above, but that in
turn broke the typedef'd struct/union/enum handling by apparently having
empty name.
I'm not sure what the right thing to do would be. I don't want to
introduce the warnings in user documentation builds.
BR,
Jani.
diff --git a/hawkmoth/util/docstr.py b/hawkmoth/util/docstr.py
index 2e6572f..100af02 100644
--- a/hawkmoth/util/docstr.py
+++ b/hawkmoth/util/docstr.py
@@ -1,5 +1,5 @@
# Copyright (c) 2016-2017 Jani Nikula <jani@xxxxxxxxxx>
-# Copyright (c) 2018-2019 Bruno Santos
<brunomanuelsantos@xxxxxxxxxxxxxxxxxx>
+# Copyright (c) 2018-2020 Bruno Santos
<brunomanuelsantos@xxxxxxxxxxxxxxxxxx>
# Licensed under the terms of BSD 2-Clause, see LICENSE for details.
"""
Documentation strings manipulation library
@@ -17,6 +17,9 @@ class Type(Enum):
TEXT = auto()
VAR = auto()
TYPE = auto()
+ STRUCT = auto()
+ UNION = auto()
+ ENUM = auto()
ENUM_VAL = auto()
MEMBER = auto()
MACRO = auto()
@@ -31,10 +34,13 @@ class Type(Enum):
Type.TEXT: (0, '\n{text}\n'),
Type.VAR: (1, '\n.. c:var:: {ttype} {name}\n\n{text}\n'),
Type.TYPE: (1, '\n.. c:type:: {name}\n\n{text}\n'),
+ Type.STRUCT: (1, '\n.. c:struct:: {name}\n\n{text}\n'),
+ Type.UNION: (1, '\n.. c:union:: {name}\n\n{text}\n'),
+ Type.ENUM: (1, '\n.. c:enum:: {name}\n\n{text}\n'),
Type.ENUM_VAL: (1, '\n.. c:macro:: {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.MACRO_FUNC: (1, '\n.. c:macro:: {name}({args})\n\n{text}\n'),
Type.FUNC: (1, '\n.. c:function:: {ttype}
{name}({args})\n\n{text}\n')
}
--
2.28.0
