odb: add LEF/DEF grammar railroad diagram docs

.github/workflows/grammar-railroad-diagrams.yml

@@ -0,0 +1,40 @@
+name: Update Grammar Railroad Diagrams
+
+on:
+  push:
+    paths:
+      - 'src/odb/src/def/def/def.y'
+      - 'src/odb/src/lef/lef/lef.y'
+
+jobs:
+  regenerate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install railroad-diagrams
+        run: pip install railroad-diagrams
+
+      - name: Regenerate railroad diagram SVGs
+        run: |
+          python3 src/odb/doc/generate_railroad_diagrams.py all
+
+      - name: Open PR if diagrams changed
+        uses: peter-evans/create-pull-request@v6
+        with:
+          commit-message: 'odb: regenerate LEF/DEF railroad diagram SVGs'
+          branch: auto/grammar-railroad-diagrams
+          title: 'odb: regenerate LEF/DEF railroad diagram SVGs'
+          body: |
+            Auto-generated by the `grammar-railroad-diagrams` workflow.
+            Triggered by a change to `def.y` or `lef.y`.
+          labels: automated

docs/toc.yml

@@ -28,6 +28,10 @@ entries:
         title: Unit Tests (Python)
       - file: main/src/odb/doc/OpenDB-AddFieldsInDbObjects
         title: Add Fields in DB Objects
+      - file: main/src/odb/doc/LEF_Grammar
+        title: LEF Grammar (Railroad Diagram)
+      - file: main/src/odb/doc/DEF_Grammar
+        title: DEF Grammar (Railroad Diagram)
   - file: main/src/gui/README
     title: GUI
   - file: main/src/par/README

src/odb/doc/DEF_Grammar.md

@@ -0,0 +1,69 @@
+# DEF Grammar (Railroad Diagram)
+
+The DEF (Design Exchange Format) grammar defines the syntax for design
+description files used by OpenROAD's ODB module. The grammar is implemented
+as a Bison parser in [`def.y`](../src/def/def/def.y).
+
+## Railroad Diagrams
+
+Railroad diagrams (syntax diagrams) give a visual representation of each
+grammar rule. The SVGs below are auto-generated from `def.y` by
+[`generate_railroad_diagrams.py`](generate_railroad_diagrams.py) and
+regenerated automatically via CI whenever `def.y` changes.
+
+### `def_file`
+![def_file](img/def_def_file.svg)
+
+### `rule`
+![rule](img/def_rule.svg)
+
+### `design_section`
+![design_section](img/def_design_section.svg)
+
+### `comps_section`
+![comps_section](img/def_comps_section.svg)
+
+### `nets_section`
+![nets_section](img/def_nets_section.svg)
+
+### `snets_section`
+![snets_section](img/def_snets_section.svg)
+
+### `pin_section`
+![pin_section](img/def_pin_section.svg)
+
+To regenerate the diagrams after editing `def.y`:
+
+```bash
+pip install railroad-diagrams
+python3 src/odb/doc/generate_railroad_diagrams.py def
+```
+
+## Top-Level Grammar Structure
+
+```
+def_file ::= version_stmt case_sens_stmt error? rule* end_design
+
+rule ::= design_section | assertions_section | blockage_section
+       | comps_section | constraint_section | extension_section
+       | fill_section | comps_maskShift_section
+       | floorplan_contraints_section [sic] | groups_section
+       | iotiming_section | nets_section | nondefaultrule_section
+       | partitions_section | pin_props_section | regions_section
+       | scanchains_section | slot_section | snets_section
+       | styles_section | timingdisables_section | via_section
+
+design_section ::= array_name | bus_bit_chars | canplace
+                 | cannotoccupy | design_name | die_area
+                 | divider_char | floorplan_name | gcellgrid
+                 | history | pin_cap_rule | pin_rule
+                 | prop_def_section | row_rule | tech_name
+                 | tracks_rule | units
+
+end_design ::= "END" "DESIGN"
+```
+
+## Source
+
+- Grammar file: [`def.y`](../src/def/def/def.y) (DEF 5.6, Bison format)
+- Full EBNF: [Issue #2488](https://github.com/The-OpenROAD-Project/OpenROAD/issues/2488)

src/odb/doc/LEF_Grammar.md

@@ -0,0 +1,63 @@
+# LEF Grammar (Railroad Diagram)
+
+The LEF (Library Exchange Format) grammar defines the syntax for library
+description files used by OpenROAD's ODB module. The grammar is implemented
+as a Bison parser in [`lef.y`](../src/lef/lef/lef.y).
+
+## Railroad Diagrams
+
+Railroad diagrams (syntax diagrams) give a visual representation of each
+grammar rule. The SVGs below are auto-generated from `lef.y` by
+[`generate_railroad_diagrams.py`](generate_railroad_diagrams.py) and
+regenerated automatically via CI whenever `lef.y` changes.
+
+### `lef_file`
+![lef_file](img/lef_lef_file.svg)
+
+### `rule`
+![rule](img/lef_rule.svg)
+
+### `layer_rule`
+![layer_rule](img/lef_layer_rule.svg)
+
+### `macro`
+![macro](img/lef_macro.svg)
+
+### `via`
+![via](img/lef_via.svg)
+
+### `site`
+![site](img/lef_site.svg)
+
+To regenerate the diagrams after editing `lef.y`:
+
+```bash
+pip install railroad-diagrams
+python3 src/odb/doc/generate_railroad_diagrams.py lef
+```
+
+## Top-Level Grammar Structure
+
+Below is a summary of the top-level LEF grammar rules for quick reference:
+
+```
+lef_file ::= error? rule* extension_opt end_library
+
+rule ::= version | busbitchars | case_sensitivity | units_section
+       | layer_rule | via | viarule | viarule_generate | dividerchar
+       | wireextension | msg_statement | spacing_rule | dielectric
+       | minfeature | irdrop | site | macro | array | def_statement
+       | nondefault_rule | prop_def_section | universalnoisemargin
+       | edgeratethreshold1 | edgeratescalefactor | edgeratethreshold2
+       | noisetable | correctiontable | input_antenna | output_antenna
+       | inout_antenna | antenna_input | antenna_inout | antenna_output
+       | manufacturing | fixedmask | useminspacing | clearancemeasure
+       | maxstack_via | create_file_statement
+
+end_library ::= ( "END" "LIBRARY" )?
+```
+
+## Source
+
+- Grammar file: [`lef.y`](../src/lef/lef/lef.y) (LEF 5.6, Bison format)
+- Full EBNF: [Issue #2488](https://github.com/The-OpenROAD-Project/OpenROAD/issues/2488)