diff --git a/docs/.gitignore b/docs/.gitignore index 65bbcdeae..09bb59048 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,5 +1,4 @@ /build/ -/source/cmd /source/generated /source/_images/**/*.log /source/_images/**/*.aux diff --git a/docs/Makefile b/docs/Makefile index a8874bb83..fb3e03b79 100644 --- a/docs/Makefile +++ b/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 diff --git a/docs/source/cmd/index_backends.rst b/docs/source/cmd/index_backends.rst new file mode 100644 index 000000000..fada942d8 --- /dev/null +++ b/docs/source/cmd/index_backends.rst @@ -0,0 +1,5 @@ +backends +------------------ + +.. autocmdgroup:: backends + :members: diff --git a/docs/source/cmd/index_formal.rst b/docs/source/cmd/index_formal.rst new file mode 100644 index 000000000..53701a437 --- /dev/null +++ b/docs/source/cmd/index_formal.rst @@ -0,0 +1,5 @@ +formal +------------------ + +.. autocmdgroup:: formal + :members: diff --git a/docs/source/cmd/index_frontends.rst b/docs/source/cmd/index_frontends.rst new file mode 100644 index 000000000..cf046e2db --- /dev/null +++ b/docs/source/cmd/index_frontends.rst @@ -0,0 +1,5 @@ +frontends +------------------ + +.. autocmdgroup:: frontends + :members: diff --git a/docs/source/cmd/index_kernel.rst b/docs/source/cmd/index_kernel.rst new file mode 100644 index 000000000..c3f323e16 --- /dev/null +++ b/docs/source/cmd/index_kernel.rst @@ -0,0 +1,5 @@ +kernel +------------------ + +.. autocmdgroup:: kernel + :members: diff --git a/docs/source/cmd/index_other.rst b/docs/source/cmd/index_other.rst new file mode 100644 index 000000000..abd41bcdc --- /dev/null +++ b/docs/source/cmd/index_other.rst @@ -0,0 +1,7 @@ +Other commands +============== + +Unknown source location + +.. autocmdgroup:: unknown + :members: diff --git a/docs/source/cmd/index_passes_cmds.rst b/docs/source/cmd/index_passes_cmds.rst new file mode 100644 index 000000000..6d2c5026d --- /dev/null +++ b/docs/source/cmd/index_passes_cmds.rst @@ -0,0 +1,5 @@ +passes/cmds +------------------ + +.. autocmdgroup:: passes/cmds + :members: diff --git a/docs/source/cmd/index_passes_equiv.rst b/docs/source/cmd/index_passes_equiv.rst new file mode 100644 index 000000000..5b0bc2741 --- /dev/null +++ b/docs/source/cmd/index_passes_equiv.rst @@ -0,0 +1,5 @@ +passes/equiv +------------------ + +.. autocmdgroup:: passes/equiv + :members: diff --git a/docs/source/cmd/index_passes_fsm.rst b/docs/source/cmd/index_passes_fsm.rst new file mode 100644 index 000000000..ddb2a9168 --- /dev/null +++ b/docs/source/cmd/index_passes_fsm.rst @@ -0,0 +1,5 @@ +passes/fsm +------------------ + +.. autocmdgroup:: passes/fsm + :members: diff --git a/docs/source/cmd/index_passes_hierarchy.rst b/docs/source/cmd/index_passes_hierarchy.rst new file mode 100644 index 000000000..1d9f237c7 --- /dev/null +++ b/docs/source/cmd/index_passes_hierarchy.rst @@ -0,0 +1,5 @@ +passes/hierarchy +------------------ + +.. autocmdgroup:: passes/hierarchy + :members: diff --git a/docs/source/cmd/index_passes_memory.rst b/docs/source/cmd/index_passes_memory.rst new file mode 100644 index 000000000..74c044135 --- /dev/null +++ b/docs/source/cmd/index_passes_memory.rst @@ -0,0 +1,5 @@ +passes/memory +------------------ + +.. autocmdgroup:: passes/memory + :members: diff --git a/docs/source/cmd/index_passes_opt.rst b/docs/source/cmd/index_passes_opt.rst new file mode 100644 index 000000000..66d78b74a --- /dev/null +++ b/docs/source/cmd/index_passes_opt.rst @@ -0,0 +1,5 @@ +passes/opt +------------------ + +.. autocmdgroup:: passes/opt + :members: diff --git a/docs/source/cmd/index_passes_pmgen.rst b/docs/source/cmd/index_passes_pmgen.rst new file mode 100644 index 000000000..aac8c1b47 --- /dev/null +++ b/docs/source/cmd/index_passes_pmgen.rst @@ -0,0 +1,5 @@ +passes/pmgen +------------------ + +.. autocmdgroup:: passes/pmgen + :members: diff --git a/docs/source/cmd/index_passes_proc.rst b/docs/source/cmd/index_passes_proc.rst new file mode 100644 index 000000000..05081f29a --- /dev/null +++ b/docs/source/cmd/index_passes_proc.rst @@ -0,0 +1,5 @@ +passes/proc +------------------ + +.. autocmdgroup:: passes/proc + :members: diff --git a/docs/source/cmd/index_passes_sat.rst b/docs/source/cmd/index_passes_sat.rst new file mode 100644 index 000000000..af041b040 --- /dev/null +++ b/docs/source/cmd/index_passes_sat.rst @@ -0,0 +1,5 @@ +passes/sat +------------------ + +.. autocmdgroup:: passes/sat + :members: diff --git a/docs/source/cmd/index_passes_techmap.rst b/docs/source/cmd/index_passes_techmap.rst new file mode 100644 index 000000000..fa9b54575 --- /dev/null +++ b/docs/source/cmd/index_passes_techmap.rst @@ -0,0 +1,5 @@ +passes/techmap +------------------ + +.. autocmdgroup:: passes/techmap + :members: diff --git a/docs/source/cmd/index_passes_tests.rst b/docs/source/cmd/index_passes_tests.rst new file mode 100644 index 000000000..72453f55f --- /dev/null +++ b/docs/source/cmd/index_passes_tests.rst @@ -0,0 +1,5 @@ +passes/tests +------------------ + +.. autocmdgroup:: passes/tests + :members: diff --git a/docs/source/cmd/index_techlibs.rst b/docs/source/cmd/index_techlibs.rst new file mode 100644 index 000000000..aeeb17c90 --- /dev/null +++ b/docs/source/cmd/index_techlibs.rst @@ -0,0 +1,5 @@ +techlibs +------------------ + +.. autocmdgroup:: techlibs + :members: diff --git a/docs/source/cmd_ref.rst b/docs/source/cmd_ref.rst index acf2d1d41..bc0707d67 100644 --- a/docs/source/cmd_ref.rst +++ b/docs/source/cmd_ref.rst @@ -8,9 +8,15 @@ Command line reference :start-at: Usage .. toctree:: - :caption: Command reference - :maxdepth: 1 - :glob: + :caption: Command reference + :maxdepth: 2 + :glob: - /appendix/env_vars - /cmd/* + /appendix/env_vars + /cmd/index_backends + /cmd/index_frontends + /cmd/index_kernel + /cmd/index_formal + /cmd/index_passes* + /cmd/index_techlibs + /cmd/index_other diff --git a/docs/util/newcmdref.py b/docs/util/newcmdref.py index d4b6aff82..6db7493af 100644 --- a/docs/util/newcmdref.py +++ b/docs/util/newcmdref.py @@ -48,25 +48,30 @@ 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' @@ -97,19 +102,8 @@ 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: - self.__cmd_lib[name] = obj + for (name, obj) in cmds_obj.get(self.lib_key, {}).items(): + self.__cmd_lib[name] = obj return self.__cmd_lib @classmethod @@ -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: