Add support for cache variable documentation in set

src/cminx/aggregator.py

@@ -36,7 +36,7 @@ class listens to all relevent parser rules, generates
 from .documentation_types import AttributeDocumentation, FunctionDocumentation, MacroDocumentation, \
     VariableDocumentation, GenericCommandDocumentation, ClassDocumentation, TestDocumentation, SectionDocumentation, \
     MethodDocumentation, VarType, CTestDocumentation, ModuleDocumentation, AbstractCommandDefinitionDocumentation, \
-    OptionDocumentation, DanglingDoccomment, DocumentationType
+    OptionDocumentation, DanglingDoccomment, DocumentationType, SetCommandKeywords, CacheVarType
 
 from .exceptions import CMakeSyntaxException
 from .parser.CMakeListener import CMakeListener
@@ -46,18 +46,6 @@ class listens to all relevent parser rules, generates
 from cminx import Settings
 
 
-class SetCommandKeywords(Enum):
-    CACHE = "CACHE"
-    PARENT_SCOPE = "PARENT_SCOPE"
-    BOOL = "BOOL"
-    PATH = "PATH"
-    STRING = "STRING"
-    INTERNAL = "INTERNAL"
-    FORCE = "FORCE"
-
-    @classmethod
-    def values(cls):
-        return [param.value for param in cls]
 
 
 @dataclass
@@ -317,11 +305,20 @@ def process_set(self, ctx: CMakeParser.Command_invocationContext, docstring: str
             )
         )
 
-        keywords = {kw: kw in params_upper for kw in SetCommandKeywords.values()}
+        keywords = {kw: kw.value in params_upper for kw in SetCommandKeywords}
+
+        if keywords[SetCommandKeywords.CACHE]:
+            cache_keyword_index = params.index(SetCommandKeywords.CACHE.value)
+            cache_var_type = CacheVarType.values()[params[cache_keyword_index + 1]]
+            cache_var_docstring = params[cache_keyword_index + 2]
+        else:
+            cache_var_type = None
+            cache_var_docstring = ""
 
         if len(values) > 1:  # List
             self.documented.append(VariableDocumentation(
-                varname, docstring, VarType.LIST, " ".join(values), keywords))
+                varname, docstring, VarType.LIST, " ".join(values), keywords, cache_var_type, cache_var_docstring
+            ))
         elif len(values) == 1:  # String
             value = ctx.single_argument()[1].getText()
 
@@ -332,10 +329,12 @@ def process_set(self, ctx: CMakeParser.Command_invocationContext, docstring: str
             if value[-1] == '"':
                 value = value[:-1]
             self.documented.append(VariableDocumentation(
-                varname, docstring, VarType.STRING, value, keywords))
+                varname, docstring, VarType.STRING, value, keywords, cache_var_type, cache_var_docstring
+            ))
         else:  # Unset
             self.documented.append(VariableDocumentation(
-                varname, docstring, VarType.UNSET, None, keywords))
+                varname, docstring, VarType.UNSET, None, keywords
+            ))
 
     def process_cpp_class(self, ctx: CMakeParser.Command_invocationContext, docstring: str) -> None:
         """
@@ -513,14 +512,16 @@ def process_option(self, ctx: CMakeParser.Command_invocationContext, docstring:
             pretty_text += f"\n{ctx.getText()}"
 
             self.logger.error(
-                f"ct_add_section() called with incorrect parameters: {params}\n\n{pretty_text}")
+                f"option() called with incorrect parameters: {params}\n\n{pretty_text}")
             return
+
         option_doc = OptionDocumentation(
             params[0],
             docstring,
             "bool",
             params[2] if len(params) == 3 else None,
             {},
+            None,
             params[1]
         )
         self.documented.append(option_doc)

src/cminx/documentation_types.py

@@ -32,6 +32,32 @@
 from .rstwriter import RSTWriter, Directive, interpreted_text
 
 
+class SetCommandKeywords(Enum):
+    CACHE = "CACHE"
+    PARENT_SCOPE = "PARENT_SCOPE"
+    BOOL = "BOOL"
+    PATH = "PATH"
+    STRING = "STRING"
+    INTERNAL = "INTERNAL"
+    FORCE = "FORCE"
+
+    @classmethod
+    def values(cls) -> list[str]:
+        return [param.value for param in cls]
+
+
+class CacheVarType(Enum):
+    BOOL = "BOOL"
+    FILEPATH = "FILEPATH"
+    PATH = "PATH"
+    STRING = "STRING"
+    INTERNAL = "INTERNAL"
+
+    @classmethod
+    def values(cls) -> dict[str, 'CacheVarType']:
+        return {param.value: param for param in cls}
+
+
 class VarType(Enum):
     """The types of variables accepted by the CMake :code:`set()` command"""
 
@@ -145,15 +171,23 @@ class VariableDocumentation(DocumentationType):
     value: Union[str, None]
     """A default value that the variable has"""
 
-    keywords: Dict[str, bool]
+    keywords: Dict[SetCommandKeywords, bool]
     """
     A dictionary between the set() command keywords and whether
     they were present / active in the documented call.
     """
 
+    cache_var_type: Union[CacheVarType, None] = None
+
+    cache_var_docstring: str = ""
+
     def process(self, writer: RSTWriter) -> None:
         d = writer.directive("data", f"{self.name}")
         d.text(self.doc)
+        if self.cache_var_type is not None:
+            d.text("Cache help text:")
+            d.text(self.cache_var_docstring)
+            d.field("FORCE", str(self.keywords[SetCommandKeywords.FORCE]))
         d.field("Default value", self.value)
         if self.type == VarType.STRING:
             var_type = "str"
@@ -163,7 +197,7 @@ def process(self, writer: RSTWriter) -> None:
             var_type = "UNSET"
         else:
             raise ValueError(f"Unknown variable type: {self.type}")
-        d.field("type", var_type)
+        d.field("type", var_type if self.cache_var_type is None else self.cache_var_type.value)
 
 
 @dataclass
@@ -173,12 +207,10 @@ class OptionDocumentation(VariableDocumentation):
     representing a user-configurable option that can
     be selected via the cache. The RST form of this documentation
     also uses the :code:`data` directive, but includes a note
-    specifying the variable is an option.
+    specifying the variable is an option. The help text is
+    the cache_var_docstring field.
     """
 
-    help_text: str
-    """The help text that the option has."""
-
     def process(self, writer: RSTWriter) -> None:
         d = writer.directive("data", f"{self.name}")
         note = d.directive("note")
@@ -189,7 +221,7 @@ def process(self, writer: RSTWriter) -> None:
             edited on the command line by the :code:`-D` flag.
             """))
         d.text(self.doc)
-        d.field("Help text", self.help_text)
+        d.field("Help text", self.cache_var_docstring)
         d.field("Default value", self.value if self.value is not None else "OFF")
         d.field("type", self.type)
 

tests/examples/example.cmake

@@ -96,6 +96,12 @@ set(MyList "Value" "Value 2")
 #]]
 set(MyString "String")
 
+#[[[
+# This is an example of a cache variable.
+# This variable is a string variable.
+#]]
+set(MyStringCache "String" CACHE STRING "Some string a user can set in cache.")
+
 #[[
 # This is an undocumented variable.
 # Unlike most other elements, it will

tests/examples/sphinx/source/example.rst

@@ -93,6 +93,21 @@ examples.example
    :type: str
 
 
+.. data:: MyStringCache
+
+   This is an example of a cache variable.
+   This variable is a string variable.
+
+   Cache help text:
+   "Some string a user can set in cache."
+
+   :FORCE: False
+
+   :Default value: String
+
+   :type: STRING
+
+
 .. function:: message("hello")
 
 

tests/examples/sphinx/source/example_no_undocumented.rst

@@ -93,6 +93,21 @@ examples.example
    :type: str
 
 
+.. data:: MyStringCache
+
+   This is an example of a cache variable.
+   This variable is a string variable.
+
+   Cache help text:
+   "Some string a user can set in cache."
+
+   :FORCE: False
+
+   :Default value: String
+
+   :type: STRING
+
+
 .. function:: message("hello")
 
 

tests/examples/sphinx/source/example_no_undocumented_diff_header.rst

@@ -93,6 +93,21 @@ examples.example.cmake
    :type: str
 
 
+.. data:: MyStringCache
+
+   This is an example of a cache variable.
+   This variable is a string variable.
+
+   Cache help text:
+   "Some string a user can set in cache."
+
+   :FORCE: False
+
+   :Default value: String
+
+   :type: STRING
+
+
 .. function:: message("hello")
 
 

tests/examples/sphinx/source/example_prefix.rst

@@ -93,6 +93,21 @@ prefix.example
    :type: str
 
 
+.. data:: MyStringCache
+
+   This is an example of a cache variable.
+   This variable is a string variable.
+
+   Cache help text:
+   "Some string a user can set in cache."
+
+   :FORCE: False
+
+   :Default value: String
+
+   :type: STRING
+
+
 .. function:: message("hello")