[hawkmoth] Re: [RFC PATCH 1/2] parser: add new sphinx 3 C domain directives

  • From: Jani Nikula <jani@xxxxxxxxxx>
  • To: Bruno Santos <brunomanuelsantos@xxxxxxxxxxxxxxxxxx>, hawkmoth mailing list <hawkmoth@xxxxxxxxxxxxx>
  • Date: Mon, 14 Dec 2020 23:16:35 +0200

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

Other related posts:

  1. Home
  2. hawkmoth
  3. Archive
  4. 12-2020