Fix file level variables with unknown types.

Previously file level variables with unknown types would cause errors in
Sphinx processing.  This was due to only the name of the variable being
passed to sphinx.  Now an attempt will be made to parse the variable's
type signature and provide that to sphinx.

closes #13

Author: speedyleion

CHANGELOG.rst

@@ -8,19 +8,25 @@ This project adheres to `Semantic Versioning <https://semver.org/>`_.
 `v0.4.0-dev`_ (unreleased)
 ==========================
 
+Changed
+-------
+
+* Undocumented constructs are no longer added to the documentation by default.
+  To maintain previous behavior add `:undoc-members:` to the project's
+  `autodoc_default_options`_.
+
 Added
 -----
 
 * `:undoc-members:` and `:no-undoc-members:` option for the autocmodule
   directive. This option set allows for controlling the listing of undocumented
   constructs.  The default is to not list undocumented constructs.
 
-  .. note:: This is a behavior change.  To maintain previous behavior add
-      `:undoc-members:` to the project's `autodoc_default_options`_.
-
 Fixes
 -----
 
+* Fix file level variables with unknown types.  Previously variables with
+  unknown types would cause an error in Sphinx processing.
 * Fix documentation of members that are arrays. Previously struct members that
   were array types would cause an error as the array size was put between the
   type and the member name.

src/sphinx_c_autodoc/loader.py

@@ -658,6 +658,54 @@ def is_public(self) -> bool:
 
         return True
 
+    def get_parsed_declaration(self) -> str:
+        """
+        Get the declaration as parsed from the :attr:`node`.
+        """
+        # Libclang will return the type as `float [20]` when looking at
+        # `float foo[20]`.  We could look at the kind `TypeKind.CONSTANTARRAY`
+        # but partitioning on the "[" just seems more straight forward.
+        type_ = self.node.type.spelling
+        type_, *(array) = type_.partition("[")
+        array_contents = "".join(array)
+
+        real_type = self._find_declaration_type()
+        type_ = type_.replace("int", real_type)
+
+        return f"{type_} {self.name} {array_contents}"
+
+    def _find_declaration_type(self) -> str:
+        """
+        Makes an attempt to try and find the identifier, and storage class,
+        representing the variable type.
+
+        Returns:
+            str: The type of the variable.  If this can't be derived falls back to
+                `int`.
+        """
+        type_ = "int"
+        tokens = list(
+            filter(
+                lambda t: t.kind == cindex.TokenKind.IDENTIFIER, self.node.get_tokens()
+            )
+        )
+        try:
+            type_ = tokens[-2].spelling
+        except IndexError:
+            # For array variables with unknown types libclang fails to provide the
+            # tokens.
+            pass
+
+        # clang doesn't provide the storage class in the type name, so we'll add it here
+        storage_keyword = ""
+        storage_class = self.node.storage_class
+        if storage_class == cindex.StorageClass.STATIC:
+            storage_keyword = "static"
+        if storage_class == cindex.StorageClass.EXTERN:
+            storage_keyword = "extern"
+
+        return f"{storage_keyword} {type_}"
+
 
 CURSORKIND_TO_OBJECT_CLASS = {
     cindex.CursorKind.TRANSLATION_UNIT: DocumentedFile,

tests/assets/c_source/file_2.c

@@ -5,6 +5,8 @@
 *
 ***************************************/
 
+unknown_type * file_level_variable[32];
+
 /**
 
 This is a type comment

tests/assets/c_source/variables.c

@@ -2,7 +2,32 @@
  * File focusing on variables
  */
 
+// Provide a way to mix defines into an unknown variable's type
+#define MAYBE_CONST
+
 /**
  * A variable
  */
-static const char * file_level_variable = "hello";
+static const char * file_level_variable = "hello";
+
+/**
+ * A variable with unknown type
+ * This one we can parse the tokens and try to replace clang's ``int``
+ * usage with a stab at the underlying type.  We can't take this token
+ * for token as sphinx is too strict at parsing and will assume that
+ * ``MAYBE_CONST`` is the type.
+ */
+static MAYBE_CONST /* throw in a pinch of comment to the mix */
+    unknown_type * unknown_type_var = 30;
+
+/**
+ * A an array variable with an unknown type.
+ * For whatever reason clang will come back with no extent on this so
+ * we have to fall back to this being treated as an int
+*/
+unknown_type unknown_array_type_var[24];
+
+/**
+ * Unknown extern type
+ */
+extern unknown_type * unknown_extern_type_var;

tests/directives/test_autocdata.py

@@ -27,9 +27,30 @@ class TestAutoCData:
         float b
         """
 
+    unknown_file_level_variable_type = """\
+        static unknown_type *unknown_type_var
+        A variable with unknown type
+        This one we can parse the tokens and try to replace clang's int
+        usage with a stab at the underlying type.  We can't take this token
+        for token as sphinx is too strict at parsing and will assume that
+        MAYBE_CONST is the type."""
+
+    unknown_file_level_array_type = """\
+        int unknown_array_type_var[24]
+        A an array variable with an unknown type.
+        For whatever reason clang will come back with no extent on this so
+        we have to fall back to this being treated as an int"""
+
+    unknown_extern_file_variable = """\
+        extern unknown_type *unknown_extern_type_var
+        Unknown extern type"""
+
     doc_data = [
         ("variables.c::file_level_variable", file_level_variable),
         ("example.c::inline_struct_variable", inline_struct_variable),
+        ("variables.c::unknown_type_var", unknown_file_level_variable_type),
+        ("variables.c::unknown_array_type_var", unknown_file_level_array_type),
+        ("variables.c::unknown_extern_type_var", unknown_extern_file_variable),
     ]
 
     @pytest.mark.parametrize("variable, expected_doc", doc_data)

tests/viewcode/test_viewcode.py

@@ -56,6 +56,7 @@ def test_viewcode_of_sphinx_project(tmp_path):
 
     chosen_links = (
         '<a class="reference internal" href="../_modules/file_2.c.html#c.unknown_member.foo"><span class="viewcode-link">[source]</span></a>',
+        '<a class="reference internal" href="../_modules/file_2.c.html#c.file_level_variable"><span class="viewcode-link">[source]</span></a>',
     )
     for l in chosen_links:
         assert l in contents