From d482df5b39f2e98f3632f2749d154763c3f2f992 Mon Sep 17 00:00:00 2001 From: Nick Date: Sat, 24 Oct 2020 12:56:54 -0700 Subject: [PATCH] Fix typedef keyword being passed to sphinx For the c type directive sphinx will throw a warning if the `typedef` keyword is provided as part of the type's signature. This also results in losing the ability to link to the type in html documentation. This has now been fixed. --- CHANGELOG.rst | 5 +++++ docs/example_c_file.rst | 1 + docs/napoleon.rst | 2 +- src/sphinx_c_autodoc/__init__.py | 11 +++++++++++ tests/assets/c_source/example.c | 5 +++++ tests/directives/test_autocstruct.py | 5 ----- tests/directives/test_autoctype.py | 9 +++++++-- 7 files changed, 30 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 60568ba7..95a43203 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -21,6 +21,11 @@ Added Fixes ----- +* No longer passing `typedef` to autodocumentation of types. + Previously the `typedef` keyword was being provided to sphinx as part of the + signature. This resulted in losing the ability to link to the type in html + documentation. + * Display of function arguments with unknown array types. Previously when a function had an argument that was an array and an unknown type, it would result in being empty in the output documentation. Now the full function diff --git a/docs/example_c_file.rst b/docs/example_c_file.rst index 48d20e5e..38d63a32 100644 --- a/docs/example_c_file.rst +++ b/docs/example_c_file.rst @@ -9,3 +9,4 @@ Begin Autodocumented C File .. autocmodule:: example.c :members: + :private-members: diff --git a/docs/napoleon.rst b/docs/napoleon.rst index e5294597..a273286f 100644 --- a/docs/napoleon.rst +++ b/docs/napoleon.rst @@ -16,7 +16,7 @@ Using this extension will take: .. literalinclude:: ../tests/assets/c_source/example.c :language: c - :lines: 70-92 + :lines: 73-95 and convert it into diff --git a/src/sphinx_c_autodoc/__init__.py b/src/sphinx_c_autodoc/__init__.py index 43bd91fa..4b293ed0 100644 --- a/src/sphinx_c_autodoc/__init__.py +++ b/src/sphinx_c_autodoc/__init__.py @@ -594,6 +594,17 @@ def consolidate_members(self) -> StringList: return self.directive.result + def format_name(self) -> str: + """Format the name of *self.object*. + + Sphinx doesn't like the typedef keyword being in typedef signatures so strip + them off here. + """ + raw_name = self.object.format_name() + + cleaned_name = raw_name.replace("typedef ", "") + return cleaned_name + class CStructDocumenter(CTypeDocumenter): """ diff --git a/tests/assets/c_source/example.c b/tests/assets/c_source/example.c index d7a59ed9..0c464b2e 100644 --- a/tests/assets/c_source/example.c +++ b/tests/assets/c_source/example.c @@ -44,6 +44,11 @@ #define MY_COOL_MACRO(_a, _b) \ some_func((_a)) +/** + * A plain old typedef + */ +typedef int a_typedef_type; + /** * Structures can be documented. * diff --git a/tests/directives/test_autocstruct.py b/tests/directives/test_autocstruct.py index 4a270ff7..2a911379 100644 --- a/tests/directives/test_autocstruct.py +++ b/tests/directives/test_autocstruct.py @@ -38,10 +38,6 @@ class TestAutoCStruct: my_struct_type foo """ - typedefed_struct = """\ - typedef intermediate_type typedefed_struct - A typedef of a struct after the fact.""" - documented_members = """\ struct documented_members A struct with documented members @@ -75,7 +71,6 @@ class TestAutoCStruct: doc_data = [ ("types.c::my_struct_type", my_struct_type), ("types.c::some_struct", some_struct), - ("types.c::typedefed_struct", typedefed_struct), ("types.c::documented_members", documented_members), ("types.c::nested_struct", nested_struct), ] diff --git a/tests/directives/test_autoctype.py b/tests/directives/test_autoctype.py index 67d8bff1..d234c00b 100644 --- a/tests/directives/test_autoctype.py +++ b/tests/directives/test_autoctype.py @@ -32,17 +32,21 @@ class TestAutoCType: # Similar to the unknown members of the union clang just falls back to # int's function_pointer_type = """\ - typedef int (int *what) + int (int *what) A function pointer type with unknown return type""" wrapped_function_pointer = """\ - typedef int (*wrapped_function_pointer)(const int *, const float) + typedef int (*wrapped_function_pointer)(const int*, const float) A function pointer wrapped on multiple lines.""" char_array = """\ typedef char char_array[10] A char array typedef""" + typedefed_struct = """\ + typedef intermediate_type typedefed_struct + A typedef of a struct after the fact.""" + doc_data = [ ("types.c::my_int", my_int), ("types.c::undocumented", undocumented), @@ -50,6 +54,7 @@ class TestAutoCType: ("types.c::what", function_pointer_type), ("types.c::wrapped_function_pointer", wrapped_function_pointer), ("types.c::char_array", char_array), + ("types.c::typedefed_struct", typedefed_struct), ] @pytest.mark.parametrize("type_, expected_doc", doc_data)