autogenerate documentation

designators.md

@@ -1,71 +1,75 @@
+# Possible Designators
+
 (copied from <https://en.wikipedia.org/wiki/Reference_designator> and edited lightly)
 
-| Designator | Component type | Implemented? |
-|:--:|:--|:--:|
-| A, ASSY | Separable assembly or sub-assembly ||
-| AE | Aerial, antenna ||
-| AT | Attenuator or isolator ||
-| B, BT, BAT | Battery | Yes |
-| BR | Bridge rectifier ||
-| C | Capacitor | Yes |
-| CV, VC | Variable capacitor | Yes |
-| CN | Connector ||
-| CRT | Cathode ray tube ||
-| D, LED, CR | Diode (all types, including LED), thyristor | Yes |
-| DL | Delay line ||
-| DS | Display, general light source, lamp, signal light ||
-| DSP | Digital signal processor ||
-| F | Fuse ||
-| FB | Ferrite bead ||
-| FD | Fiducial ||
-| FET | Field-effect transistor ||
-| FL | Filter ||
-| G | Generator or oscillator ||
-| GDT, SVP | Gas discharge tube, Surge Voltage Protector ||
-| GN | General network ||
-| H | Pin header ||
-| HY | Circulator or directional coupler ||
-| IC, U | Integrated circuit | Partial |
-| IR | Infrared Diode | Yes |
-| J | Jack (least-movable connector of a connector pair) ||
-| J, JW | Wire link ("jumper") ||
-| JFET | Junction gate field-effect transistor ||
-| JP | Jumper (Link) ||
-| K, RY, RLA | Relay or contactor ||
-| L | Inductor or coil or ferrite bead ||
-| LA | Lightning arrester ||
-| LCD | Liquid crystal display ||
-| LDR | Light-dependent resistor ||
-| LS | Loudspeaker or buzzer ||
-| M | Motor ||
-| MCB | Miniature circuit breaker ||
-| MIC, MK | Microphone ||
-| MOSFET | Metal-oxide-semiconductor field-effect transistor ||
-| MP | Mechanical part (including screws and fasteners) ||
-| NE | Neon lamp ||
-| OP | Opto-isolator ||
-| P | Plug (most-movable connector of a connector pair) ||
-| PCB | Printed circuit board ||
-| PLC | Programmable logic controller ||
-| PS | Power supply ||
-| PU | Pickup ||
-| Q | Transistor (all types) ||
-| R | Resistor | Yes |
-| RV, VR | Variable resistor (potentiometer or rheostat) | Yes |
-| RN | Resistor network ||
-| RT | Thermistor ||
-| S, SW | Switch (all types, including buttons) ||
-| SCR | Silicon-controlled rectifier ||
-| SUS | Silicon unilateral switch ||
-| T | Transformer ||
-| TC | Thermocouple ||
-| TFT | Thin-film transistor (display) ||
-| TH | Thermistor ||
-| TP | Test point ||
-| TUN | Tuner ||
-| V | Vacuum tube ||
-| VDR, MOV | Voltage-dependent resistor (varistor) ||
-| VFD | Vacuum fluorescent display ||
-| VT | Voltage transformer ||
-| W | Wire | (implicit) |
-| X, XTAL, Y | Crystal oscillator, ceramic resonator ||
+This is a list of all components that Schemascii *might* support. For a complete list of all supported components, (generated from the implementation file), please see [supported-components.md](./supported-components.md). If a component you want is not supported, have a look at [#3](https://github.com/dragoncoder047/schemascii/issues/3) or fork and implement it yourself.
+
+| Designator | Component type |
+|:--:|:--|
+| A, ASSY | Separable assembly or sub-assembly |
+| AE | Aerial, antenna |
+| AT | Attenuator or isolator |
+| B, BT, BAT | Battery |
+| BR | Bridge rectifier |
+| C | Capacitor |
+| CV, VC | Variable capacitor |
+| CN | Connector |
+| CRT | Cathode ray tube |
+| D, LED, CR | Diode (all types, including LED), thyristor |
+| DL | Delay line |
+| DS | Display, general light source, lamp, signal light |
+| DSP | Digital signal processor |
+| F | Fuse |
+| FB | Ferrite bead |
+| FD | Fiducial |
+| FET | Field-effect transistor |
+| FL | Filter |
+| G | Generator or oscillator |
+| GDT, SVP | Gas discharge tube, Surge Voltage Protector |
+| GN | General network |
+| H | Pin header |
+| HY | Circulator or directional coupler |
+| IC, U | Integrated circuit |
+| IR | Infrared Diode |
+| J | Jack (least-movable connector of a connector pair) |
+| J, JW | Wire link ("jumper") |
+| JFET | Junction gate field-effect transistor |
+| JP | Jumper (Link) |
+| K, RY, RLA | Relay or contactor |
+| L | Inductor or coil or ferrite bead |
+| LA | Lightning arrester |
+| LCD | Liquid crystal display |
+| LDR | Light-dependent resistor |
+| LS | Loudspeaker or buzzer |
+| M | Motor |
+| MCB | Miniature circuit breaker |
+| MIC, MK | Microphone |
+| MOSFET | Metal-oxide-semiconductor field-effect transistor |
+| MP | Mechanical part (including screws and fasteners) |
+| NE | Neon lamp |
+| OP | Opto-isolator |
+| P | Plug (most-movable connector of a connector pair) |
+| PCB | Printed circuit board |
+| PLC | Programmable logic controller |
+| PS | Power supply |
+| PU | Pickup |
+| Q | Transistor (all types) |
+| R | Resistor |
+| RV, VR | Variable resistor (potentiometer or rheostat) |
+| RN | Resistor network |
+| RT | Thermistor |
+| S, SW | Switch (all types, including buttons) |
+| SCR | Silicon-controlled rectifier |
+| SUS | Silicon unilateral switch |
+| T | Transformer |
+| TC | Thermocouple |
+| TFT | Thin-film transistor (display) |
+| TH | Thermistor |
+| TP | Test point |
+| TUN | Tuner |
+| V | Vacuum tube |
+| VDR, MOV | Voltage-dependent resistor (varistor) |
+| VFD | Vacuum fluorescent display |
+| VT | Voltage transformer |
+| W | Wire |
+| X, XTAL, Y | Crystal oscillator, ceramic resonator |

schemascii/components_render.py

@@ -39,6 +39,7 @@ def n_check(
                     f"{box.type}{box.id} component can only "
                     f"have {n_terminals} terminals")
             return func(box, terminals, bom_data, **options)
+        n_check.__doc__ = func.__doc__
         return n_check
     return n_inner
 
@@ -60,6 +61,7 @@ def de_ambiguous(
             terminals,
             bom_data[0],
             **options)
+    de_ambiguous.__doc__ = func.__doc__
     return de_ambiguous
 
 
@@ -82,6 +84,7 @@ def sort_terminals(
             terminals,
             bom_data,
             **options)
+    sort_terminals.__doc__ = func.__doc__
     return sort_terminals
 
 
@@ -90,7 +93,8 @@ def resistor(
         terminals: list[Terminal],
         bom_data: BOMData,
         **options):
-    "Draw a resistor"
+    """Resistor, Variable resistor, etc.
+    bom:ohms[,watts]"""
     t1, t2 = terminals[0].pt, terminals[1].pt
     vec = t1 - t2
     mid = (t1 + t2) / 2
@@ -122,7 +126,9 @@ def capacitor(
         terminals: list[Terminal],
         bom_data: BOMData,
         **options):
-    "Draw a capacitor"
+    """Draw a capacitor, variable capacitor, etc.
+    bom:farads[,volts]
+    flags:+=positive"""
     t1, t2 = terminals[0].pt, terminals[1].pt
     mid = (t1 + t2) / 2
     angle = phase(t1 - t2)
@@ -149,7 +155,9 @@ def battery(
         terminals: list[Terminal],
         bom_data: BOMData,
         **options):
-    "Draw a battery cell"
+    """Draw a battery cell.
+    bom:volts[,amp-hours]
+    flags:+=positive"""
     t1, t2 = terminals[0].pt, terminals[1].pt
     mid = (t1 + t2) / 2
     angle = phase(t1 - t2)
@@ -176,7 +184,9 @@ def diode(
         terminals: list[Terminal],
         bom_data: BOMData,
         **options):
-    "Draw a diode or LED"
+    """Draw a diode or LED.
+    bom:part-number
+    flags:+=positive"""
     t1, t2 = terminals[0].pt, terminals[1].pt
     mid = (t1 + t2) / 2
     angle = phase(t1 - t2)
@@ -209,7 +219,8 @@ def integrated_circuit(
         terminals: list[Terminal],
         bom_data: BOMData,
         **options):
-    "Draw an IC"
+    """Draw an IC.
+    bom:part-number[,pin1-label[,pin2-label[,...]]]"""
     label_style = options["label"]
     scale = options["scale"]
     sz = (box.p2 - box.p1) * scale
@@ -270,7 +281,8 @@ def jack(
         terminals: list[Terminal],
         bom_data: BOMData,
         **options):
-    "Draw a jack connector or plug"
+    """Draw a jack connector or plug.
+    bom:label"""
     scale = options["scale"]
     sc_t1 = terminals[0].pt * scale
     sc_t2 = sc_t1 + rect(scale, SIDE_TO_ANGLE_MAP[terminals[0].side])
@@ -301,8 +313,10 @@ def transistor(
         terminals: list[Terminal],
         bom_data: BOMData,
         **options):
-    "Draw a bipolar transistor (PNP/NPN) or FET (NFET/PFET)"
-    if all(x not in bom_data.data.lower() for x in ("pnp:", "npn:", "nfet:", "pfet:")):
+    """Draw a bipolar transistor (PNP/NPN) or FET (NFET/PFET).
+    bom:{npn/pnp/nfet/pfet}:part-number
+    flags:s=source,d=drain,g=gate,e=emitter,c=collector,b=base"""
+    if not any(bom_data.data.lower().startswith(x) for x in ("pnp:", "npn:", "nfet:", "pfet:")):
         raise BOMError(
             f"Need type of transistor for {box.type}{box.id}")
     silicon_type, part_num = bom_data.data.split(":")
@@ -314,21 +328,17 @@ def transistor(
         ae, se, ctl = sort_for_flags(terminals, box, "e", "c", "b")
     ap, sp = ae.pt, se.pt
     diff = sp - ap
-    try:
-        slope = diff.imag / diff.real
-    except ZeroDivisionError:
+    if diff.real == 0:
         mid = complex(ap.real, ctl.pt.imag)
+    elif diff.imag == 0:
+        mid = complex(ctl.pt.real, ap.imag)
     else:
-        try:
-            diff.real / diff.imag
-        except ZeroDivisionError:
-            mid = complex(ctl.pt.real, ap.imag)
-        else:
-            # From wolfram alpha "solve m*(x-x1)+y1=(-1/m)*(x-x2)+y2 for x"
-            # x = (m^2 x1 - m y1 + m y2 + x2)/(m^2 + 1)
-            mid_x = (slope ** 2 * ap.real - slope * ap.imag + slope *
-                    ctl.pt.imag + ctl.pt.real) / (slope ** 2 + 1)
-            mid = complex(mid_x, slope * (mid_x - ap.real) + ap.imag)
+        # From wolfram alpha "solve m*(x-x1)+y1=(-1/m)*(x-x2)+y2 for x"
+        # x = (m^2 x1 - m y1 + m y2 + x2)/(m^2 + 1)
+        slope = diff.imag / diff.real
+        mid_x = (slope ** 2 * ap.real - slope * ap.imag + slope *
+                ctl.pt.imag + ctl.pt.real) / (slope ** 2 + 1)
+        mid = complex(mid_x, slope * (mid_x - ap.real) + ap.imag)
     theta = phase(ap - sp)
     backwards = 1 if is_clockwise([ae, se, ctl]) else -1
     thetaquarter = theta + (backwards * pi / 2)

scripts/cdoc.py

@@ -0,0 +1,53 @@
+#! /usr/bin/env python3
+import re
+from itertools import groupby
+from schemascii.components_render import RENDERERS
+
+# pylint: disable=unspecified-encoding,missing-function-docstring,invalid-name,not-an-iterable
+# cSpell:ignore siht etareneg redner iicsa stpircs
+# cSpell:ignore mehcs daetsn detareneg yllacitamotua codc stnenopmoc
+
+TOP = ("# Supported Schemascii Components\n\n<!--\n"
+       + "".join(reversed(".elif siht etareneg-er ot yp.codc/"
+                          "stpircs nur dna yp.redner_stnenopmoc/iicsa"
+                          "mehcs tide ,daetsnI\n!TIDE TON OD\n!ELIF"
+                          " DETARENEG YLLACITAMOTUA")) +
+       "\n-->\n\n| Reference Designators | Description | BOM Syntax | Supported Flags |"
+       "\n|:--:|:--|:--:|:--|\n")
+
+
+def group_components_by_func():
+    items = groupby(list(RENDERERS.items()), lambda x: x[1])
+    out = {}
+    for x, g in items:
+        out[x] = [p[0] for p in g]
+    return out
+
+
+def parse_docstring(d):
+    out = [None, None, None]
+    if fs := re.search(r"flags:(.*?)$", d, re.M):
+        out[2] = [f.split("=") for f in fs.group(1).split(",")]
+        d = d.replace(fs.group(), "")
+    if b := re.search(r"bom:(.*?)$", d, re.M):
+        out[1] = b.group(1)
+        d = d.replace(b.group(), "")
+    out[0] = d.strip()
+    return out
+
+
+def main():
+    content = TOP
+    for func, rds in group_components_by_func().items():
+        data = parse_docstring(func.__doc__)
+        content += "| " + ", ".join(f"`{x}`" for x in rds) + " | "
+        content += data[0].replace("\n", "<br>") + " | "
+        content += "`" + data[1] + "` | "
+        content += "<br>".join(f"`{x[0]}` = {x[1]}" for x in (data[2] or []))
+        content += " |\n"
+    with open("supported-components.md", "w") as f:
+        f.write(content)
+
+
+if __name__ == '__main__':
+    main()

supported-components.md

@@ -0,0 +1,17 @@
+# Supported Schemascii Components
+
+<!--
+AUTOMATICALLY GENERATED FILE!
+DO NOT EDIT!
+Instead, edit schemascii/components_render.py and run scripts/cdoc.py to re-generate this file.
+-->
+
+| Reference Designators | Description | BOM Syntax | Supported Flags |
+|:--:|:--|:--:|:--|
+| `R`, `RV`, `VR` | Resistor, Variable resistor, etc. | `ohms[,watts]` |  |
+| `C`, `CV`, `VC` | Draw a capacitor, variable capacitor, etc. | `farads[,volts]` | `+` = positive |
+| `B`, `BT`, `BAT` | Draw a battery cell. | `volts[,amp-hours]` | `+` = positive |
+| `D`, `LED`, `CR`, `IR` | Draw a diode or LED. | `part-number` | `+` = positive |
+| `U`, `IC` | Draw an IC. | `part-number[,pin1-label[,pin2-label[,...]]]` |  |
+| `J`, `P` | Draw a jack connector or plug. | `label` |  |
+| `Q`, `MOSFET`, `MOS`, `FET` | Draw a bipolar transistor (PNP/NPN) or FET (NFET/PFET). | `{npn/pnp/nfet/pfet}:part-number` | `s` = source<br>`d` = drain<br>`g` = gate<br>`e` = emitter<br>`c` = collector<br>`b` = base |