Docs: Grouping changes

Keep techlibs folder hierarchy.
techlibs/* and passes/* groups are now nested under index_techlibs and index_passes respectively, with most (all?) of the passes/* pages getting proper headings, as well as backends/frontends/kernel.  `index_passes_techmap` also references `index_techlibs`.
Split command reference toc in twain, one with maxdepth=2 and one with maxdepth=3, since passes and techlibs now have an extra level of nesting.
Move the `cmd_ref` link to the command reference, instead of top of the page.
Remove `index_internal` and `index_other` from the toc, and mark the pages as orphan. Internal commands get a note callout after the command reference toc (although this doesn't work for the pdf build), while other commands are linked in the warning for missing `source_location` (since that *should* be the only time when there are any commands in the "unknown" group).
Update autodoc extension versions, and mark the directives extension as not `parallel_read_safe` (it might be, but I'm not sure about how the xref lookups work if it is parallel so better to be safe).

docs/source/cmd/index_backends.rst

@@ -1,5 +1,5 @@
-backends
+Writing output files
-------------------
+--------------------
 
 .. autocmdgroup:: backends
    :members:

docs/source/cmd/index_frontends.rst

@@ -1,5 +1,5 @@
-frontends
+Reading input files
-------------------
+-------------------
 
 .. autocmdgroup:: frontends
    :members:

docs/source/cmd/index_internal.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 internal
 ------------------
 

docs/source/cmd/index_kernel.rst

@@ -1,5 +1,5 @@
-kernel
+Yosys kernel commands
-------------------
+---------------------
 
 .. autocmdgroup:: kernel
    :members:

docs/source/cmd/index_other.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 Other commands
 ==============
 

docs/source/cmd/index_passes.rst

@@ -0,0 +1,14 @@
+Passes
+------
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   /cmd/index_passes_hierarchy
+   /cmd/index_passes_proc
+   /cmd/index_passes_fsm
+   /cmd/index_passes_memory
+   /cmd/index_passes_opt
+   /cmd/index_passes_techmap
+   /cmd/index_passes_*

docs/source/cmd/index_passes_cmds.rst

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

docs/source/cmd/index_passes_equiv.rst

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

docs/source/cmd/index_passes_fsm.rst

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

docs/source/cmd/index_passes_hierarchy.rst

@@ -1,4 +1,4 @@
-passes/hierarchy
+hierarchy
 ------------------
 
 .. autocmdgroup:: passes/hierarchy

docs/source/cmd/index_passes_memory.rst

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

docs/source/cmd/index_passes_opt.rst

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

docs/source/cmd/index_passes_proc.rst

@@ -1,5 +1,5 @@
-passes/proc
+Converting process blocks
-------------------
+-------------------------
 
 .. autocmdgroup:: passes/proc
    :members:

docs/source/cmd/index_passes_sat.rst

@@ -1,4 +1,4 @@
-passes/sat
+sat
 ------------------
 
 .. autocmdgroup:: passes/sat

docs/source/cmd/index_passes_techmap.rst

@@ -1,5 +1,7 @@
-passes/techmap
+Technology mapping
 ------------------
 
+.. seealso:: :doc:`/cmd/index_techlibs`
+
 .. autocmdgroup:: passes/techmap
    :members:

docs/source/cmd/index_techlibs.rst

@@ -1,9 +1,11 @@
-techlibs
+Technology libraries
-------------------
+====================
 
-.. TODO:: disambiguate `synth_intel` and `synth_intel_alm`
+Listed in alphabetical order.
 
-   (MAX10, Cyclone IV) and (Cyclone V, Arria V, Cyclone 10 GX) respectively
+.. toctree::
+   :maxdepth: 2
+   :glob:
 
-.. autocmdgroup:: techlibs
+   /cmd/index_techlibs_common
-   :members:
+   /cmd/index_techlibs_*

docs/source/cmd/index_techlibs_achronix.rst

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

docs/source/cmd/index_techlibs_anlogic.rst

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

docs/source/cmd/index_techlibs_common.rst

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

docs/source/cmd/index_techlibs_coolrunner2.rst

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

docs/source/cmd/index_techlibs_easic.rst

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

docs/source/cmd/index_techlibs_ecp5.rst

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

docs/source/cmd/index_techlibs_fabulous.rst

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

docs/source/cmd/index_techlibs_gatemate.rst

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

docs/source/cmd/index_techlibs_gowin.rst

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

docs/source/cmd/index_techlibs_greenpak4.rst

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

docs/source/cmd/index_techlibs_ice40.rst

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

docs/source/cmd/index_techlibs_intel.rst

@@ -0,0 +1,5 @@
+Intel (MAX10, Cyclone IV)
+-------------------------
+
+.. autocmdgroup:: techlibs/intel
+   :members:

docs/source/cmd/index_techlibs_intel_alm.rst

@@ -0,0 +1,5 @@
+Intel ALM (Cyclone V, Arria V, Cyclone 10 GX)
+---------------------------------------------
+
+.. autocmdgroup:: techlibs/intel_alm
+   :members:

docs/source/cmd/index_techlibs_lattice.rst

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

docs/source/cmd/index_techlibs_microchip.rst

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

docs/source/cmd/index_techlibs_nanoxplore.rst

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

docs/source/cmd/index_techlibs_nexus.rst

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

docs/source/cmd/index_techlibs_quicklogic.rst

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

docs/source/cmd/index_techlibs_sf2.rst

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

docs/source/cmd/index_techlibs_xilinx.rst

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

docs/source/cmd_ref.rst

@@ -1,5 +1,3 @@
-.. _cmd_ref:
-
 ================================================================================
 Command line reference
 ================================================================================
@@ -7,17 +5,31 @@ Command line reference
 .. literalinclude:: /generated/yosys
     :start-at: Usage
 
+.. _cmd_ref:
+
+Command reference
+-----------------
+
+.. todo:: Can we warn on command groups that aren't included anywhere?
+
 .. toctree::
-   :caption: Command reference
    :maxdepth: 2
-   :glob:
 
    /appendix/env_vars
-   /cmd/index_backends
    /cmd/index_frontends
+   /cmd/index_backends
    /cmd/index_kernel
    /cmd/index_formal
-   /cmd/index_passes*
+
+.. toctree::
+   :maxdepth: 3
+
+   /cmd/index_passes
    /cmd/index_techlibs
-   /cmd/index_internal
+
-   /cmd/index_other
+.. TODO:: Fix index_internal not being included in pdf
+
+.. note::
+
+   Commands intended for internal developer use can also be found under
+   :doc:`/cmd/index_internal`

docs/source/index.rst

@@ -5,7 +5,7 @@ Yosys Open SYnthesis Suite
 Yosys is an open source framework for RTL synthesis.  To learn more about Yosys,
 see :doc:`/introduction`.  For a quick guide on how to get started using Yosys,
 check out :doc:`/getting_started/index`.  For the complete list of commands
-available, go to :ref:`commandindex`.
+available, go to :ref:`cmd_ref`.
 
 .. todo:: look into command ref improvements
 

docs/util/cmd_documenter.py

@@ -228,13 +228,20 @@ class YosysCmdGroupDocumenter(Documenter):
 
         sourcename = self.get_sourcename()
 
-        if not self.import_object():
+        imported_object = self.import_object();
+        if self.lib_key == 'groups' and self.name == 'unknown':
+            if imported_object:
+                logger.warning(f"Found commands assigned to group {self.name}: {[x[0] for x in self.object]}", type='cmdref')
+            else:
+                return
+        elif not imported_object:
             log_msg = f"unable to load {self.name} with {type(self)}"
             if self.lib_key == 'groups':
                 logger.info(log_msg, type = 'cmdref')
                 self.add_line(f'.. warning:: No commands found for group {self.name!r}', sourcename)
                 self.add_line('', sourcename)
                 self.add_line('   Documentation may have been built without ``source_location`` support.', sourcename)
+                self.add_line('   Try check :doc:`/cmd/index_other`.', sourcename)
             else:
                 logger.warning(log_msg, type = 'cmdref')
             return
@@ -401,6 +408,6 @@ def setup(app: Sphinx) -> dict[str, Any]:
     app.add_autodocumenter(YosysCmdGroupDocumenter)
     app.add_autodocumenter(YosysCmdDocumenter)
     return {
-        'version': '1',
+        'version': '2',
         'parallel_read_safe': True,
     }

docs/util/custom_directives.py

@@ -735,4 +735,7 @@ def setup(app: Sphinx):
 
     app.add_role('autoref', autoref)
     
-    return {'version': '0.2'}
+    return {
+        'version': '0.3',    
+        'parallel_read_safe': False,
+    }

kernel/register.cc

@@ -989,8 +989,6 @@ struct HelpPass : public Pass {
 					cmd_help.group = "backends";
 				else if (source_file.find("frontends/") == 0 || (!has_source && name.find("write_") == 0))
 					cmd_help.group = "frontends";
-				else if (source_file.find("techlibs/") == 0 || (!has_source && name.find("synth_") == 0))
-					cmd_help.group = "techlibs";
 				else if (has_source) {
 					auto last_slash = source_file.find_last_of('/');
 					if (last_slash != string::npos) {