From a74aeb13010c5b0c072a28ad55b02ac40567d152 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 21 Mar 2025 10:26:12 +1300 Subject: [PATCH] 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 | 4 +-- docs/source/cmd/index_frontends.rst | 4 +-- docs/source/cmd/index_internal.rst | 2 ++ docs/source/cmd/index_kernel.rst | 4 +-- docs/source/cmd/index_other.rst | 2 ++ docs/source/cmd/index_passes.rst | 14 ++++++++++ docs/source/cmd/index_passes_cmds.rst | 4 +-- docs/source/cmd/index_passes_equiv.rst | 4 +-- docs/source/cmd/index_passes_fsm.rst | 4 +-- docs/source/cmd/index_passes_hierarchy.rst | 2 +- docs/source/cmd/index_passes_memory.rst | 4 +-- docs/source/cmd/index_passes_opt.rst | 4 +-- docs/source/cmd/index_passes_proc.rst | 4 +-- docs/source/cmd/index_passes_sat.rst | 2 +- docs/source/cmd/index_passes_techmap.rst | 4 ++- docs/source/cmd/index_techlibs.rst | 14 ++++++---- docs/source/cmd/index_techlibs_achronix.rst | 5 ++++ docs/source/cmd/index_techlibs_anlogic.rst | 5 ++++ docs/source/cmd/index_techlibs_common.rst | 5 ++++ .../source/cmd/index_techlibs_coolrunner2.rst | 5 ++++ docs/source/cmd/index_techlibs_easic.rst | 5 ++++ docs/source/cmd/index_techlibs_ecp5.rst | 5 ++++ docs/source/cmd/index_techlibs_fabulous.rst | 5 ++++ docs/source/cmd/index_techlibs_gatemate.rst | 5 ++++ docs/source/cmd/index_techlibs_gowin.rst | 5 ++++ docs/source/cmd/index_techlibs_greenpak4.rst | 5 ++++ docs/source/cmd/index_techlibs_ice40.rst | 5 ++++ docs/source/cmd/index_techlibs_intel.rst | 5 ++++ docs/source/cmd/index_techlibs_intel_alm.rst | 5 ++++ docs/source/cmd/index_techlibs_lattice.rst | 5 ++++ docs/source/cmd/index_techlibs_microchip.rst | 5 ++++ docs/source/cmd/index_techlibs_nanoxplore.rst | 5 ++++ docs/source/cmd/index_techlibs_nexus.rst | 5 ++++ docs/source/cmd/index_techlibs_quicklogic.rst | 5 ++++ docs/source/cmd/index_techlibs_sf2.rst | 5 ++++ docs/source/cmd/index_techlibs_xilinx.rst | 5 ++++ docs/source/cmd_ref.rst | 28 +++++++++++++------ docs/source/index.rst | 2 +- docs/util/cmd_documenter.py | 11 ++++++-- docs/util/custom_directives.py | 5 +++- kernel/register.cc | 2 -- 41 files changed, 183 insertions(+), 41 deletions(-) create mode 100644 docs/source/cmd/index_passes.rst create mode 100644 docs/source/cmd/index_techlibs_achronix.rst create mode 100644 docs/source/cmd/index_techlibs_anlogic.rst create mode 100644 docs/source/cmd/index_techlibs_common.rst create mode 100644 docs/source/cmd/index_techlibs_coolrunner2.rst create mode 100644 docs/source/cmd/index_techlibs_easic.rst create mode 100644 docs/source/cmd/index_techlibs_ecp5.rst create mode 100644 docs/source/cmd/index_techlibs_fabulous.rst create mode 100644 docs/source/cmd/index_techlibs_gatemate.rst create mode 100644 docs/source/cmd/index_techlibs_gowin.rst create mode 100644 docs/source/cmd/index_techlibs_greenpak4.rst create mode 100644 docs/source/cmd/index_techlibs_ice40.rst create mode 100644 docs/source/cmd/index_techlibs_intel.rst create mode 100644 docs/source/cmd/index_techlibs_intel_alm.rst create mode 100644 docs/source/cmd/index_techlibs_lattice.rst create mode 100644 docs/source/cmd/index_techlibs_microchip.rst create mode 100644 docs/source/cmd/index_techlibs_nanoxplore.rst create mode 100644 docs/source/cmd/index_techlibs_nexus.rst create mode 100644 docs/source/cmd/index_techlibs_quicklogic.rst create mode 100644 docs/source/cmd/index_techlibs_sf2.rst create mode 100644 docs/source/cmd/index_techlibs_xilinx.rst diff --git a/docs/source/cmd/index_backends.rst b/docs/source/cmd/index_backends.rst index fada942d8..373c26def 100644 --- a/docs/source/cmd/index_backends.rst +++ b/docs/source/cmd/index_backends.rst @@ -1,5 +1,5 @@ -backends ------------------- +Writing output files +-------------------- .. autocmdgroup:: backends :members: diff --git a/docs/source/cmd/index_frontends.rst b/docs/source/cmd/index_frontends.rst index cf046e2db..b64fdc9b9 100644 --- a/docs/source/cmd/index_frontends.rst +++ b/docs/source/cmd/index_frontends.rst @@ -1,5 +1,5 @@ -frontends ------------------- +Reading input files +------------------- .. autocmdgroup:: frontends :members: diff --git a/docs/source/cmd/index_internal.rst b/docs/source/cmd/index_internal.rst index c1b7f5eb8..127010980 100644 --- a/docs/source/cmd/index_internal.rst +++ b/docs/source/cmd/index_internal.rst @@ -1,3 +1,5 @@ +:orphan: + internal ------------------ diff --git a/docs/source/cmd/index_kernel.rst b/docs/source/cmd/index_kernel.rst index c3f323e16..c6891b5e5 100644 --- a/docs/source/cmd/index_kernel.rst +++ b/docs/source/cmd/index_kernel.rst @@ -1,5 +1,5 @@ -kernel ------------------- +Yosys kernel commands +--------------------- .. autocmdgroup:: kernel :members: diff --git a/docs/source/cmd/index_other.rst b/docs/source/cmd/index_other.rst index abd41bcdc..540cf9e49 100644 --- a/docs/source/cmd/index_other.rst +++ b/docs/source/cmd/index_other.rst @@ -1,3 +1,5 @@ +:orphan: + Other commands ============== diff --git a/docs/source/cmd/index_passes.rst b/docs/source/cmd/index_passes.rst new file mode 100644 index 000000000..b652be004 --- /dev/null +++ b/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_* diff --git a/docs/source/cmd/index_passes_cmds.rst b/docs/source/cmd/index_passes_cmds.rst index 6d2c5026d..c7d9fa0a3 100644 --- a/docs/source/cmd/index_passes_cmds.rst +++ b/docs/source/cmd/index_passes_cmds.rst @@ -1,5 +1,5 @@ -passes/cmds ------------------- +General passes +-------------- .. autocmdgroup:: passes/cmds :members: diff --git a/docs/source/cmd/index_passes_equiv.rst b/docs/source/cmd/index_passes_equiv.rst index 5b0bc2741..6ed2c3c18 100644 --- a/docs/source/cmd/index_passes_equiv.rst +++ b/docs/source/cmd/index_passes_equiv.rst @@ -1,5 +1,5 @@ -passes/equiv ------------------- +Equivalence checking +-------------------- .. autocmdgroup:: passes/equiv :members: diff --git a/docs/source/cmd/index_passes_fsm.rst b/docs/source/cmd/index_passes_fsm.rst index ddb2a9168..43af5dce6 100644 --- a/docs/source/cmd/index_passes_fsm.rst +++ b/docs/source/cmd/index_passes_fsm.rst @@ -1,5 +1,5 @@ -passes/fsm ------------------- +FSM handling +------------ .. autocmdgroup:: passes/fsm :members: diff --git a/docs/source/cmd/index_passes_hierarchy.rst b/docs/source/cmd/index_passes_hierarchy.rst index 1d9f237c7..2032be636 100644 --- a/docs/source/cmd/index_passes_hierarchy.rst +++ b/docs/source/cmd/index_passes_hierarchy.rst @@ -1,4 +1,4 @@ -passes/hierarchy +hierarchy ------------------ .. autocmdgroup:: passes/hierarchy diff --git a/docs/source/cmd/index_passes_memory.rst b/docs/source/cmd/index_passes_memory.rst index 74c044135..b4edb88e7 100644 --- a/docs/source/cmd/index_passes_memory.rst +++ b/docs/source/cmd/index_passes_memory.rst @@ -1,5 +1,5 @@ -passes/memory ------------------- +Memory handling +--------------- .. autocmdgroup:: passes/memory :members: diff --git a/docs/source/cmd/index_passes_opt.rst b/docs/source/cmd/index_passes_opt.rst index 66d78b74a..ddeb5ce10 100644 --- a/docs/source/cmd/index_passes_opt.rst +++ b/docs/source/cmd/index_passes_opt.rst @@ -1,5 +1,5 @@ -passes/opt ------------------- +Optimization passes +------------------- .. autocmdgroup:: passes/opt :members: diff --git a/docs/source/cmd/index_passes_proc.rst b/docs/source/cmd/index_passes_proc.rst index 05081f29a..1ad8d85b4 100644 --- a/docs/source/cmd/index_passes_proc.rst +++ b/docs/source/cmd/index_passes_proc.rst @@ -1,5 +1,5 @@ -passes/proc ------------------- +Converting process blocks +------------------------- .. autocmdgroup:: passes/proc :members: diff --git a/docs/source/cmd/index_passes_sat.rst b/docs/source/cmd/index_passes_sat.rst index af041b040..1f2c6904d 100644 --- a/docs/source/cmd/index_passes_sat.rst +++ b/docs/source/cmd/index_passes_sat.rst @@ -1,4 +1,4 @@ -passes/sat +sat ------------------ .. autocmdgroup:: passes/sat diff --git a/docs/source/cmd/index_passes_techmap.rst b/docs/source/cmd/index_passes_techmap.rst index fa9b54575..1682cd181 100644 --- a/docs/source/cmd/index_passes_techmap.rst +++ b/docs/source/cmd/index_passes_techmap.rst @@ -1,5 +1,7 @@ -passes/techmap +Technology mapping ------------------ +.. seealso:: :doc:`/cmd/index_techlibs` + .. autocmdgroup:: passes/techmap :members: diff --git a/docs/source/cmd/index_techlibs.rst b/docs/source/cmd/index_techlibs.rst index c80fccf5f..043620a3b 100644 --- a/docs/source/cmd/index_techlibs.rst +++ b/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 - :members: + /cmd/index_techlibs_common + /cmd/index_techlibs_* diff --git a/docs/source/cmd/index_techlibs_achronix.rst b/docs/source/cmd/index_techlibs_achronix.rst new file mode 100644 index 000000000..babf4e979 --- /dev/null +++ b/docs/source/cmd/index_techlibs_achronix.rst @@ -0,0 +1,5 @@ +achronix +------------------ + +.. autocmdgroup:: techlibs/achronix + :members: diff --git a/docs/source/cmd/index_techlibs_anlogic.rst b/docs/source/cmd/index_techlibs_anlogic.rst new file mode 100644 index 000000000..13ef12fc7 --- /dev/null +++ b/docs/source/cmd/index_techlibs_anlogic.rst @@ -0,0 +1,5 @@ +anlogic +------------------ + +.. autocmdgroup:: techlibs/anlogic + :members: diff --git a/docs/source/cmd/index_techlibs_common.rst b/docs/source/cmd/index_techlibs_common.rst new file mode 100644 index 000000000..532f4291e --- /dev/null +++ b/docs/source/cmd/index_techlibs_common.rst @@ -0,0 +1,5 @@ +Generic +------------------ + +.. autocmdgroup:: techlibs/common + :members: diff --git a/docs/source/cmd/index_techlibs_coolrunner2.rst b/docs/source/cmd/index_techlibs_coolrunner2.rst new file mode 100644 index 000000000..23e87d03e --- /dev/null +++ b/docs/source/cmd/index_techlibs_coolrunner2.rst @@ -0,0 +1,5 @@ +coolrunner2 +------------------ + +.. autocmdgroup:: techlibs/coolrunner2 + :members: diff --git a/docs/source/cmd/index_techlibs_easic.rst b/docs/source/cmd/index_techlibs_easic.rst new file mode 100644 index 000000000..0cd375f11 --- /dev/null +++ b/docs/source/cmd/index_techlibs_easic.rst @@ -0,0 +1,5 @@ +easic +------------------ + +.. autocmdgroup:: techlibs/easic + :members: diff --git a/docs/source/cmd/index_techlibs_ecp5.rst b/docs/source/cmd/index_techlibs_ecp5.rst new file mode 100644 index 000000000..42a12e8e9 --- /dev/null +++ b/docs/source/cmd/index_techlibs_ecp5.rst @@ -0,0 +1,5 @@ +ecp5 +------------------ + +.. autocmdgroup:: techlibs/ecp5 + :members: diff --git a/docs/source/cmd/index_techlibs_fabulous.rst b/docs/source/cmd/index_techlibs_fabulous.rst new file mode 100644 index 000000000..ce075c025 --- /dev/null +++ b/docs/source/cmd/index_techlibs_fabulous.rst @@ -0,0 +1,5 @@ +fabulous +------------------ + +.. autocmdgroup:: techlibs/fabulous + :members: diff --git a/docs/source/cmd/index_techlibs_gatemate.rst b/docs/source/cmd/index_techlibs_gatemate.rst new file mode 100644 index 000000000..5a362b0fe --- /dev/null +++ b/docs/source/cmd/index_techlibs_gatemate.rst @@ -0,0 +1,5 @@ +gatemate +------------------ + +.. autocmdgroup:: techlibs/gatemate + :members: diff --git a/docs/source/cmd/index_techlibs_gowin.rst b/docs/source/cmd/index_techlibs_gowin.rst new file mode 100644 index 000000000..379cb773e --- /dev/null +++ b/docs/source/cmd/index_techlibs_gowin.rst @@ -0,0 +1,5 @@ +gowin +------------------ + +.. autocmdgroup:: techlibs/gowin + :members: diff --git a/docs/source/cmd/index_techlibs_greenpak4.rst b/docs/source/cmd/index_techlibs_greenpak4.rst new file mode 100644 index 000000000..1f733488d --- /dev/null +++ b/docs/source/cmd/index_techlibs_greenpak4.rst @@ -0,0 +1,5 @@ +greenpak4 +------------------ + +.. autocmdgroup:: techlibs/greenpak4 + :members: diff --git a/docs/source/cmd/index_techlibs_ice40.rst b/docs/source/cmd/index_techlibs_ice40.rst new file mode 100644 index 000000000..3d04fee05 --- /dev/null +++ b/docs/source/cmd/index_techlibs_ice40.rst @@ -0,0 +1,5 @@ +ice40 +------------------ + +.. autocmdgroup:: techlibs/ice40 + :members: diff --git a/docs/source/cmd/index_techlibs_intel.rst b/docs/source/cmd/index_techlibs_intel.rst new file mode 100644 index 000000000..6b3a26222 --- /dev/null +++ b/docs/source/cmd/index_techlibs_intel.rst @@ -0,0 +1,5 @@ +Intel (MAX10, Cyclone IV) +------------------------- + +.. autocmdgroup:: techlibs/intel + :members: diff --git a/docs/source/cmd/index_techlibs_intel_alm.rst b/docs/source/cmd/index_techlibs_intel_alm.rst new file mode 100644 index 000000000..afadfc13e --- /dev/null +++ b/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: diff --git a/docs/source/cmd/index_techlibs_lattice.rst b/docs/source/cmd/index_techlibs_lattice.rst new file mode 100644 index 000000000..55bed7afc --- /dev/null +++ b/docs/source/cmd/index_techlibs_lattice.rst @@ -0,0 +1,5 @@ +lattice +------------------ + +.. autocmdgroup:: techlibs/lattice + :members: diff --git a/docs/source/cmd/index_techlibs_microchip.rst b/docs/source/cmd/index_techlibs_microchip.rst new file mode 100644 index 000000000..79340febc --- /dev/null +++ b/docs/source/cmd/index_techlibs_microchip.rst @@ -0,0 +1,5 @@ +microchip +------------------ + +.. autocmdgroup:: techlibs/microchip + :members: diff --git a/docs/source/cmd/index_techlibs_nanoxplore.rst b/docs/source/cmd/index_techlibs_nanoxplore.rst new file mode 100644 index 000000000..c941c32ba --- /dev/null +++ b/docs/source/cmd/index_techlibs_nanoxplore.rst @@ -0,0 +1,5 @@ +nanoxplore +------------------ + +.. autocmdgroup:: techlibs/nanoxplore + :members: diff --git a/docs/source/cmd/index_techlibs_nexus.rst b/docs/source/cmd/index_techlibs_nexus.rst new file mode 100644 index 000000000..a0289a571 --- /dev/null +++ b/docs/source/cmd/index_techlibs_nexus.rst @@ -0,0 +1,5 @@ +nexus +------------------ + +.. autocmdgroup:: techlibs/nexus + :members: diff --git a/docs/source/cmd/index_techlibs_quicklogic.rst b/docs/source/cmd/index_techlibs_quicklogic.rst new file mode 100644 index 000000000..d11d4faca --- /dev/null +++ b/docs/source/cmd/index_techlibs_quicklogic.rst @@ -0,0 +1,5 @@ +quicklogic +------------------ + +.. autocmdgroup:: techlibs/quicklogic + :members: diff --git a/docs/source/cmd/index_techlibs_sf2.rst b/docs/source/cmd/index_techlibs_sf2.rst new file mode 100644 index 000000000..b97f96c9d --- /dev/null +++ b/docs/source/cmd/index_techlibs_sf2.rst @@ -0,0 +1,5 @@ +sf2 +------------------ + +.. autocmdgroup:: techlibs/sf2 + :members: diff --git a/docs/source/cmd/index_techlibs_xilinx.rst b/docs/source/cmd/index_techlibs_xilinx.rst new file mode 100644 index 000000000..5ce3d115b --- /dev/null +++ b/docs/source/cmd/index_techlibs_xilinx.rst @@ -0,0 +1,5 @@ +xilinx +------------------ + +.. autocmdgroup:: techlibs/xilinx + :members: diff --git a/docs/source/cmd_ref.rst b/docs/source/cmd_ref.rst index 37b6966ef..73a383ad5 100644 --- a/docs/source/cmd_ref.rst +++ b/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` diff --git a/docs/source/index.rst b/docs/source/index.rst index 61dc114ef..403100093 100644 --- a/docs/source/index.rst +++ b/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 diff --git a/docs/util/cmd_documenter.py b/docs/util/cmd_documenter.py index 61753fa57..52f3d2cf4 100644 --- a/docs/util/cmd_documenter.py +++ b/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, } diff --git a/docs/util/custom_directives.py b/docs/util/custom_directives.py index a263e06ab..041472386 100644 --- a/docs/util/custom_directives.py +++ b/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, + } diff --git a/kernel/register.cc b/kernel/register.cc index 4df3474be..a853576f2 100644 --- a/kernel/register.cc +++ b/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) {