Skip to content

Commit ed13296

Browse files
dragoncoder047dragoncoder047
authored
autogenerate documentation
1 parent 67b1c43 commit ed13296

File tree

5 files changed

+174
-90
lines changed

5 files changed

+174
-90
lines changed

‎designators.md

+73-69
Original file line numberDiff line numberDiff line change
@@ -1,71 +1,75 @@
1+
# Possible Designators
2+
13
(copied from <https://en.wikipedia.org/wiki/Reference_designator> and edited lightly)
24

3-
| Designator | Component type | Implemented? |
4-
|:--:|:--|:--:|
5-
| A, ASSY | Separable assembly or sub-assembly ||
6-
| AE | Aerial, antenna ||
7-
| AT | Attenuator or isolator ||
8-
| B, BT, BAT | Battery | Yes |
9-
| BR | Bridge rectifier ||
10-
| C | Capacitor | Yes |
11-
| CV, VC | Variable capacitor | Yes |
12-
| CN | Connector ||
13-
| CRT | Cathode ray tube ||
14-
| D, LED, CR | Diode (all types, including LED), thyristor | Yes |
15-
| DL | Delay line ||
16-
| DS | Display, general light source, lamp, signal light ||
17-
| DSP | Digital signal processor ||
18-
| F | Fuse ||
19-
| FB | Ferrite bead ||
20-
| FD | Fiducial ||
21-
| FET | Field-effect transistor ||
22-
| FL | Filter ||
23-
| G | Generator or oscillator ||
24-
| GDT, SVP | Gas discharge tube, Surge Voltage Protector ||
25-
| GN | General network ||
26-
| H | Pin header ||
27-
| HY | Circulator or directional coupler ||
28-
| IC, U | Integrated circuit | Partial |
29-
| IR | Infrared Diode | Yes |
30-
| J | Jack (least-movable connector of a connector pair) ||
31-
| J, JW | Wire link ("jumper") ||
32-
| JFET | Junction gate field-effect transistor ||
33-
| JP | Jumper (Link) ||
34-
| K, RY, RLA | Relay or contactor ||
35-
| L | Inductor or coil or ferrite bead ||
36-
| LA | Lightning arrester ||
37-
| LCD | Liquid crystal display ||
38-
| LDR | Light-dependent resistor ||
39-
| LS | Loudspeaker or buzzer ||
40-
| M | Motor ||
41-
| MCB | Miniature circuit breaker ||
42-
| MIC, MK | Microphone ||
43-
| MOSFET | Metal-oxide-semiconductor field-effect transistor ||
44-
| MP | Mechanical part (including screws and fasteners) ||
45-
| NE | Neon lamp ||
46-
| OP | Opto-isolator ||
47-
| P | Plug (most-movable connector of a connector pair) ||
48-
| PCB | Printed circuit board ||
49-
| PLC | Programmable logic controller ||
50-
| PS | Power supply ||
51-
| PU | Pickup ||
52-
| Q | Transistor (all types) ||
53-
| R | Resistor | Yes |
54-
| RV, VR | Variable resistor (potentiometer or rheostat) | Yes |
55-
| RN | Resistor network ||
56-
| RT | Thermistor ||
57-
| S, SW | Switch (all types, including buttons) ||
58-
| SCR | Silicon-controlled rectifier ||
59-
| SUS | Silicon unilateral switch ||
60-
| T | Transformer ||
61-
| TC | Thermocouple ||
62-
| TFT | Thin-film transistor (display) ||
63-
| TH | Thermistor ||
64-
| TP | Test point ||
65-
| TUN | Tuner ||
66-
| V | Vacuum tube ||
67-
| VDR, MOV | Voltage-dependent resistor (varistor) ||
68-
| VFD | Vacuum fluorescent display ||
69-
| VT | Voltage transformer ||
70-
| W | Wire | (implicit) |
71-
| X, XTAL, Y | Crystal oscillator, ceramic resonator ||
5+
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.
6+
7+
| Designator | Component type |
8+
|:--:|:--|
9+
| A, ASSY | Separable assembly or sub-assembly |
10+
| AE | Aerial, antenna |
11+
| AT | Attenuator or isolator |
12+
| B, BT, BAT | Battery |
13+
| BR | Bridge rectifier |
14+
| C | Capacitor |
15+
| CV, VC | Variable capacitor |
16+
| CN | Connector |
17+
| CRT | Cathode ray tube |
18+
| D, LED, CR | Diode (all types, including LED), thyristor |
19+
| DL | Delay line |
20+
| DS | Display, general light source, lamp, signal light |
21+
| DSP | Digital signal processor |
22+
| F | Fuse |
23+
| FB | Ferrite bead |
24+
| FD | Fiducial |
25+
| FET | Field-effect transistor |
26+
| FL | Filter |
27+
| G | Generator or oscillator |
28+
| GDT, SVP | Gas discharge tube, Surge Voltage Protector |
29+
| GN | General network |
30+
| H | Pin header |
31+
| HY | Circulator or directional coupler |
32+
| IC, U | Integrated circuit |
33+
| IR | Infrared Diode |
34+
| J | Jack (least-movable connector of a connector pair) |
35+
| J, JW | Wire link ("jumper") |
36+
| JFET | Junction gate field-effect transistor |
37+
| JP | Jumper (Link) |
38+
| K, RY, RLA | Relay or contactor |
39+
| L | Inductor or coil or ferrite bead |
40+
| LA | Lightning arrester |
41+
| LCD | Liquid crystal display |
42+
| LDR | Light-dependent resistor |
43+
| LS | Loudspeaker or buzzer |
44+
| M | Motor |
45+
| MCB | Miniature circuit breaker |
46+
| MIC, MK | Microphone |
47+
| MOSFET | Metal-oxide-semiconductor field-effect transistor |
48+
| MP | Mechanical part (including screws and fasteners) |
49+
| NE | Neon lamp |
50+
| OP | Opto-isolator |
51+
| P | Plug (most-movable connector of a connector pair) |
52+
| PCB | Printed circuit board |
53+
| PLC | Programmable logic controller |
54+
| PS | Power supply |
55+
| PU | Pickup |
56+
| Q | Transistor (all types) |
57+
| R | Resistor |
58+
| RV, VR | Variable resistor (potentiometer or rheostat) |
59+
| RN | Resistor network |
60+
| RT | Thermistor |
61+
| S, SW | Switch (all types, including buttons) |
62+
| SCR | Silicon-controlled rectifier |
63+
| SUS | Silicon unilateral switch |
64+
| T | Transformer |
65+
| TC | Thermocouple |
66+
| TFT | Thin-film transistor (display) |
67+
| TH | Thermistor |
68+
| TP | Test point |
69+
| TUN | Tuner |
70+
| V | Vacuum tube |
71+
| VDR, MOV | Voltage-dependent resistor (varistor) |
72+
| VFD | Vacuum fluorescent display |
73+
| VT | Voltage transformer |
74+
| W | Wire |
75+
| X, XTAL, Y | Crystal oscillator, ceramic resonator |

‎schemascii/components_render.py

+31-21
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ def n_check(
3939
f"{box.type}{box.id} component can only "
4040
f"have {n_terminals} terminals")
4141
return func(box, terminals, bom_data, **options)
42+
n_check.__doc__ = func.__doc__
4243
return n_check
4344
return n_inner
4445

@@ -60,6 +61,7 @@ def de_ambiguous(
6061
terminals,
6162
bom_data[0],
6263
**options)
64+
de_ambiguous.__doc__ = func.__doc__
6365
return de_ambiguous
6466

6567

@@ -82,6 +84,7 @@ def sort_terminals(
8284
terminals,
8385
bom_data,
8486
**options)
87+
sort_terminals.__doc__ = func.__doc__
8588
return sort_terminals
8689

8790

@@ -90,7 +93,8 @@ def resistor(
9093
terminals: list[Terminal],
9194
bom_data: BOMData,
9295
**options):
93-
"Draw a resistor"
96+
"""Resistor, Variable resistor, etc.
97+
bom:ohms[,watts]"""
9498
t1, t2 = terminals[0].pt, terminals[1].pt
9599
vec = t1 - t2
96100
mid = (t1 + t2) / 2
@@ -122,7 +126,9 @@ def capacitor(
122126
terminals: list[Terminal],
123127
bom_data: BOMData,
124128
**options):
125-
"Draw a capacitor"
129+
"""Draw a capacitor, variable capacitor, etc.
130+
bom:farads[,volts]
131+
flags:+=positive"""
126132
t1, t2 = terminals[0].pt, terminals[1].pt
127133
mid = (t1 + t2) / 2
128134
angle = phase(t1 - t2)
@@ -149,7 +155,9 @@ def battery(
149155
terminals: list[Terminal],
150156
bom_data: BOMData,
151157
**options):
152-
"Draw a battery cell"
158+
"""Draw a battery cell.
159+
bom:volts[,amp-hours]
160+
flags:+=positive"""
153161
t1, t2 = terminals[0].pt, terminals[1].pt
154162
mid = (t1 + t2) / 2
155163
angle = phase(t1 - t2)
@@ -176,7 +184,9 @@ def diode(
176184
terminals: list[Terminal],
177185
bom_data: BOMData,
178186
**options):
179-
"Draw a diode or LED"
187+
"""Draw a diode or LED.
188+
bom:part-number
189+
flags:+=positive"""
180190
t1, t2 = terminals[0].pt, terminals[1].pt
181191
mid = (t1 + t2) / 2
182192
angle = phase(t1 - t2)
@@ -209,7 +219,8 @@ def integrated_circuit(
209219
terminals: list[Terminal],
210220
bom_data: BOMData,
211221
**options):
212-
"Draw an IC"
222+
"""Draw an IC.
223+
bom:part-number[,pin1-label[,pin2-label[,...]]]"""
213224
label_style = options["label"]
214225
scale = options["scale"]
215226
sz = (box.p2 - box.p1) * scale
@@ -270,7 +281,8 @@ def jack(
270281
terminals: list[Terminal],
271282
bom_data: BOMData,
272283
**options):
273-
"Draw a jack connector or plug"
284+
"""Draw a jack connector or plug.
285+
bom:label"""
274286
scale = options["scale"]
275287
sc_t1 = terminals[0].pt * scale
276288
sc_t2 = sc_t1 + rect(scale, SIDE_TO_ANGLE_MAP[terminals[0].side])
@@ -301,8 +313,10 @@ def transistor(
301313
terminals: list[Terminal],
302314
bom_data: BOMData,
303315
**options):
304-
"Draw a bipolar transistor (PNP/NPN) or FET (NFET/PFET)"
305-
if all(x not in bom_data.data.lower() for x in ("pnp:", "npn:", "nfet:", "pfet:")):
316+
"""Draw a bipolar transistor (PNP/NPN) or FET (NFET/PFET).
317+
bom:{npn/pnp/nfet/pfet}:part-number
318+
flags:s=source,d=drain,g=gate,e=emitter,c=collector,b=base"""
319+
if not any(bom_data.data.lower().startswith(x) for x in ("pnp:", "npn:", "nfet:", "pfet:")):
306320
raise BOMError(
307321
f"Need type of transistor for {box.type}{box.id}")
308322
silicon_type, part_num = bom_data.data.split(":")
@@ -314,21 +328,17 @@ def transistor(
314328
ae, se, ctl = sort_for_flags(terminals, box, "e", "c", "b")
315329
ap, sp = ae.pt, se.pt
316330
diff = sp - ap
317-
try:
318-
slope = diff.imag / diff.real
319-
except ZeroDivisionError:
331+
if diff.real == 0:
320332
mid = complex(ap.real, ctl.pt.imag)
333+
elif diff.imag == 0:
334+
mid = complex(ctl.pt.real, ap.imag)
321335
else:
322-
try:
323-
diff.real / diff.imag
324-
except ZeroDivisionError:
325-
mid = complex(ctl.pt.real, ap.imag)
326-
else:
327-
# From wolfram alpha "solve m*(x-x1)+y1=(-1/m)*(x-x2)+y2 for x"
328-
# x = (m^2 x1 - m y1 + m y2 + x2)/(m^2 + 1)
329-
mid_x = (slope ** 2 * ap.real - slope * ap.imag + slope *
330-
ctl.pt.imag + ctl.pt.real) / (slope ** 2 + 1)
331-
mid = complex(mid_x, slope * (mid_x - ap.real) + ap.imag)
336+
# From wolfram alpha "solve m*(x-x1)+y1=(-1/m)*(x-x2)+y2 for x"
337+
# x = (m^2 x1 - m y1 + m y2 + x2)/(m^2 + 1)
338+
slope = diff.imag / diff.real
339+
mid_x = (slope ** 2 * ap.real - slope * ap.imag + slope *
340+
ctl.pt.imag + ctl.pt.real) / (slope ** 2 + 1)
341+
mid = complex(mid_x, slope * (mid_x - ap.real) + ap.imag)
332342
theta = phase(ap - sp)
333343
backwards = 1 if is_clockwise([ae, se, ctl]) else -1
334344
thetaquarter = theta + (backwards * pi / 2)

‎scripts/cdoc.py

+53
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
#! /usr/bin/env python3
2+
import re
3+
from itertools import groupby
4+
from schemascii.components_render import RENDERERS
5+
6+
# pylint: disable=unspecified-encoding,missing-function-docstring,invalid-name,not-an-iterable
7+
# cSpell:ignore siht etareneg redner iicsa stpircs
8+
# cSpell:ignore mehcs daetsn detareneg yllacitamotua codc stnenopmoc
9+
10+
TOP = ("# Supported Schemascii Components\n\n<!--\n"
11+
+ "".join(reversed(".elif siht etareneg-er ot yp.codc/"
12+
"stpircs nur dna yp.redner_stnenopmoc/iicsa"
13+
"mehcs tide ,daetsnI\n!TIDE TON OD\n!ELIF"
14+
" DETARENEG YLLACITAMOTUA")) +
15+
"\n-->\n\n| Reference Designators | Description | BOM Syntax | Supported Flags |"
16+
"\n|:--:|:--|:--:|:--|\n")
17+
18+
19+
def group_components_by_func():
20+
items = groupby(list(RENDERERS.items()), lambda x: x[1])
21+
out = {}
22+
for x, g in items:
23+
out[x] = [p[0] for p in g]
24+
return out
25+
26+
27+
def parse_docstring(d):
28+
out = [None, None, None]
29+
if fs := re.search(r"flags:(.*?)$", d, re.M):
30+
out[2] = [f.split("=") for f in fs.group(1).split(",")]
31+
d = d.replace(fs.group(), "")
32+
if b := re.search(r"bom:(.*?)$", d, re.M):
33+
out[1] = b.group(1)
34+
d = d.replace(b.group(), "")
35+
out[0] = d.strip()
36+
return out
37+
38+
39+
def main():
40+
content = TOP
41+
for func, rds in group_components_by_func().items():
42+
data = parse_docstring(func.__doc__)
43+
content += "| " + ", ".join(f"`{x}`" for x in rds) + " | "
44+
content += data[0].replace("\n", "<br>") + " | "
45+
content += "`" + data[1] + "` | "
46+
content += "<br>".join(f"`{x[0]}` = {x[1]}" for x in (data[2] or []))
47+
content += " |\n"
48+
with open("supported-components.md", "w") as f:
49+
f.write(content)
50+
51+
52+
if __name__ == '__main__':
53+
main()

‎release.py renamed to ‎scripts/release.py

File renamed without changes.

‎supported-components.md

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Supported Schemascii Components
2+
3+
<!--
4+
AUTOMATICALLY GENERATED FILE!
5+
DO NOT EDIT!
6+
Instead, edit schemascii/components_render.py and run scripts/cdoc.py to re-generate this file.
7+
-->
8+
9+
| Reference Designators | Description | BOM Syntax | Supported Flags |
10+
|:--:|:--|:--:|:--|
11+
| `R`, `RV`, `VR` | Resistor, Variable resistor, etc. | `ohms[,watts]` | |
12+
| `C`, `CV`, `VC` | Draw a capacitor, variable capacitor, etc. | `farads[,volts]` | `+` = positive |
13+
| `B`, `BT`, `BAT` | Draw a battery cell. | `volts[,amp-hours]` | `+` = positive |
14+
| `D`, `LED`, `CR`, `IR` | Draw a diode or LED. | `part-number` | `+` = positive |
15+
| `U`, `IC` | Draw an IC. | `part-number[,pin1-label[,pin2-label[,...]]]` | |
16+
| `J`, `P` | Draw a jack connector or plug. | `label` | |
17+
| `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 |

0 commit comments

Comments
 (0)