Docs: Group commands

Removes group parsing from command ref domain, instead relying on a 'groups' object in the cmds.json file.
`docs/source/cmd` is no longer ignored or cleaned.

docs/.gitignore

@@ -1,5 +1,4 @@
 /build/
-/source/cmd
 /source/generated
 /source/_images/**/*.log
 /source/_images/**/*.aux

docs/Makefile

@@ -47,7 +47,7 @@ help:
 .PHONY: clean
 clean: clean-examples
 	rm -rf $(BUILDDIR)/*
-	rm -rf source/cmd util/__pycache__
+	rm -rf util/__pycache__
 	rm -rf source/generated
 	$(MAKE) -C source/_images clean
 

docs/source/cmd/index_backends.rst

@@ -0,0 +1,5 @@
+backends
+------------------
+
+.. autocmdgroup:: backends
+   :members:

docs/source/cmd/index_formal.rst

@@ -0,0 +1,5 @@
+formal
+------------------
+
+.. autocmdgroup:: formal
+   :members:

docs/source/cmd/index_frontends.rst

@@ -0,0 +1,5 @@
+frontends
+------------------
+
+.. autocmdgroup:: frontends
+   :members:

docs/source/cmd/index_kernel.rst

@@ -0,0 +1,5 @@
+kernel
+------------------
+
+.. autocmdgroup:: kernel
+   :members:

docs/source/cmd/index_other.rst

@@ -0,0 +1,7 @@
+Other commands
+==============
+
+Unknown source location
+
+.. autocmdgroup:: unknown
+   :members:

docs/source/cmd/index_passes_cmds.rst

@@ -0,0 +1,5 @@
+passes/cmds
+------------------
+
+.. autocmdgroup:: passes/cmds
+   :members:

docs/source/cmd/index_passes_equiv.rst

@@ -0,0 +1,5 @@
+passes/equiv
+------------------
+
+.. autocmdgroup:: passes/equiv
+   :members:

docs/source/cmd/index_passes_fsm.rst

@@ -0,0 +1,5 @@
+passes/fsm
+------------------
+
+.. autocmdgroup:: passes/fsm
+   :members:

docs/source/cmd/index_passes_hierarchy.rst

@@ -0,0 +1,5 @@
+passes/hierarchy
+------------------
+
+.. autocmdgroup:: passes/hierarchy
+   :members:

docs/source/cmd/index_passes_memory.rst

@@ -0,0 +1,5 @@
+passes/memory
+------------------
+
+.. autocmdgroup:: passes/memory
+   :members:

docs/source/cmd/index_passes_opt.rst

@@ -0,0 +1,5 @@
+passes/opt
+------------------
+
+.. autocmdgroup:: passes/opt
+   :members:

docs/source/cmd/index_passes_pmgen.rst

@@ -0,0 +1,5 @@
+passes/pmgen
+------------------
+
+.. autocmdgroup:: passes/pmgen
+   :members:

docs/source/cmd/index_passes_proc.rst

@@ -0,0 +1,5 @@
+passes/proc
+------------------
+
+.. autocmdgroup:: passes/proc
+   :members:

docs/source/cmd/index_passes_sat.rst

@@ -0,0 +1,5 @@
+passes/sat
+------------------
+
+.. autocmdgroup:: passes/sat
+   :members:

docs/source/cmd/index_passes_techmap.rst

@@ -0,0 +1,5 @@
+passes/techmap
+------------------
+
+.. autocmdgroup:: passes/techmap
+   :members:

docs/source/cmd/index_passes_tests.rst

@@ -0,0 +1,5 @@
+passes/tests
+------------------
+
+.. autocmdgroup:: passes/tests
+   :members:

docs/source/cmd/index_techlibs.rst

@@ -0,0 +1,5 @@
+techlibs
+------------------
+
+.. autocmdgroup:: techlibs
+   :members:

docs/source/cmd_ref.rst

@@ -9,8 +9,14 @@ Command line reference
 
 .. toctree::
    :caption: Command reference
-	:maxdepth: 1
+   :maxdepth: 2
    :glob:
 
    /appendix/env_vars
-	/cmd/*
+   /cmd/index_backends
+   /cmd/index_frontends
+   /cmd/index_kernel
+   /cmd/index_formal
+   /cmd/index_passes*
+   /cmd/index_techlibs
+   /cmd/index_other

docs/util/newcmdref.py

@@ -48,26 +48,31 @@ class YosysCmd:
     name: str
     title: str
     content: list[YosysCmdContentListing]
+    group: str
     source_file: str
+    source_line: int
+    source_func: str
     experimental_flag: bool
 
     def __init__(
             self,
             name:str = "", title:str = "",
             content: list[dict[str]] = [],
-            source_file:str = 'unknown',
+            group: str = 'unknown',
+            source_file: str = "",
+            source_line: int = 0,
+            source_func: str = "",
             experimental_flag: bool = False
     ) -> None:
         self.name = name
         self.title = title
         self.content = [YosysCmdContentListing(**c) for c in content]
+        self.group = group
         self.source_file = source_file
+        self.source_line = source_line
+        self.source_func = source_func
         self.experimental_flag = experimental_flag
     
-    @property
-    def source_line(self) -> int:
-        return 0
-    
 class YosysCmdGroupDocumenter(Documenter):
     objtype = 'cmdgroup'
     priority = 10
@@ -97,18 +102,7 @@ class YosysCmdGroupDocumenter(Documenter):
                     subtype = 'cmd_lib'
                 )
                 cmds_obj = {}
-            for (name, obj) in cmds_obj.get('cmds', {}).items():
-                if self.lib_key == 'groups':
-                    source_file: str = obj.get('source_file', 'unknown')
-                    if source_file == 'unknown':
-                        source_group = 'unknown'
-                    else:
-                        source_group = str(Path(source_file).parent)
-                    try:
-                        self.__cmd_lib[source_group].append(name)
-                    except KeyError:
-                        self.__cmd_lib[source_group] = [name,]
-                else:
+            for (name, obj) in cmds_obj.get(self.lib_key, {}).items():
                 self.__cmd_lib[name] = obj
         return self.__cmd_lib
     
@@ -332,6 +326,7 @@ class YosysCmdDocumenter(YosysCmdGroupDocumenter):
         # set sourcename and add content from attribute documentation
         domain = getattr(self, 'domain', self.objtype)
         source_name = self.object.source_file
+        source_line = self.object.source_line
 
         def render(content_list: YosysCmdContentListing, indent: int=0):
             content_source = content_list.source_file or source_name
@@ -363,7 +358,7 @@ class YosysCmdDocumenter(YosysCmdGroupDocumenter):
 
         if self.get_sourcename() != 'unknown':
             self.add_line('\n', source_name)
-            self.add_line(f'.. note:: Help text automatically generated from :file:`{source_name}`', source_name)
+            self.add_line(f'.. note:: Help text automatically generated from :file:`{source_name}:{source_line}`', source_name)
 
         # add additional content (e.g. from document), if present
         if more_content: