10000 make docs · dragoncoder047/schemascii@d8726cc · GitHub
[go: up one dir, main page]
Skip to content

Commit d8726cc

Browse files
dragoncoder047dragoncoder047
committed
make docs
1 parent a13bd71 commit d8726cc

File tree

5 files changed

+217
-88
lines changed

5 files changed

+217
-88
lines changed

‎options.md

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
2+
# Data Section Options
3+
4+
<!-- This file was automatically generated by scripts/docs.py
5+
on Fri Sep 13 12:59:48 2024 -->
6+
7+
## Scope `:WIRE-TAG`
8+
9+
| Option | Value | Description | Default |
10+
|:------:|:-----:|:------------|:-------:|
11+
| scale | float | Scale by which to enlarge the entire diagram by | 15 |
12+
| linewidth | float | Width of drawn lines | 2 |
13+
| color | str | Default color for everything | 'black' |
14+
15+
## Scope `:WIRE`
16+
17+
| Option | Value | Description | Default |
18+
|:------:|:-----:|:------------|:-------:|
19+
| scale | float | Scale by which to enlarge the entire diagram by | 15 |
20+
| linewidth | float | Width of drawn lines | 2 |
21+
| color | str | Default color for everything | 'black' |
22+
23+
## Scope `:NET`
24+
25+
| Option | Value | Description | Default |
26+
|:------:|:-----:|:------------|:-------:|
27+
| scale | float | Scale by which to enlarge the entire diagram by | 15 |
28+
| linewidth | float | Width of drawn lines | 2 |
29+
| color | str | Default color for everything | 'black' |
30+
31+
## Scope `:COMPONENT`
32+
33+
| Option | Value | Description | Default |
34+
|:------:|:-----:|:------------|:-------:|
35+
| scale | float | Scale by which to enlarge the entire diagram by | 15 |
36+
| linewidth | float | Width of drawn lines | 2 |
37+
| color | str | Default color for everything | 'black' |
38+
| offset_scale | float | How far to offset the label from the center of the component. Relative to the global scale option. | 1 |
39+
| font | str | Text font for labels | 'monospace' |
40+
41+
## Scope `:ANNOTATION`
42+
43+
| Option | Value | Description | Default |
44+
|:------:|:-----:|:------------|:-------:|
45+
| scale | float | Scale by which to enlarge the entire diagram by | 15 |
46+
| linewidth | float | Width of drawn lines | 2 |
47+
| color | str | Default color for everything | 'black' |
48+
| font | str | Text font | 'sans-serif' |
49+
50+
## Scope `:ANNOTATION-LINE`
51+
52+
| Option | Value | Description | Default |
53+
|:------:|:-----:|:------------|:-------:|
54+
| scale | float | Scale by which to enlarge the entire diagram by | 15 |
55+
| linewidth | float | Width of drawn lines | 2 |
56+
| color | str | Default color for everything | 'black' |
57+
58+
## Scope `:ROOT`
59+
60+
| Option | Value | Description | Default |
61+
|:------:|:-----:|:------------|:-------:|
62+
| scale | float | Scale by which to enlarge the entire diagram by | 15 |
63+
| padding | float | Margin around the border of the drawing | 10 |
64+
65+
## Component `:BATTERY`
66+
67+
Reference Designators: `B`, `BT`, `BAT`
68+
69+
| Option | Value | Description | Default |
70+
|:------:|:-----:|:------------|:-------:|
71+
| scale | float | Scale by which to enlarge the entire diagram by | 15 |
72+
| linewidth | float | Width of drawn lines | 2 |
73+
| color | str | Default color for everything | 'black' |
74+
| offset_scale | float | How far to offset the label from the center of the component. Relative to the global scale option. | 1 |
75+
| font | str | Text font for labels | 'monospace' |
76+
| value | str | Battery voltage | (required) |
77+
| capacity | str | Battery capacity in amp-hours | (no value) |
78+
79+
## Component `:CAPACITOR`
80+
81+
Reference Designators: `C`, `VC`, `CV`
82+
83+
| Option | Value | Description | Default |
84+
|:------:|:-----:|:------------|:-------:|
85+
| scale | float | Scale by which to enlarge the entire diagram by | 15 |
86+
| linewidth | float | Width of drawn lines | 2 |
87+
| color | str | Default color for everything | 'black' |
88+
| offset_scale | float | How far to offset the label from the center of the component. Relative to the global scale option. | 1 |
89+
| font | str | Text font for labels | 'monospace' |
90+
| value | str | Capacitance in farads | (required) |
91+
| voltage | str | Maximum voltage tolerance in volts | (no value) |
92+
93+
## Component `:INDUCTOR`
94+
95+
Reference Designators: `L`, `VL`, `LV`
96+
97+
| Option | Value | Description | Default |
98+
|:------:|:-----:|:------------|:-------:|
99+
| scale | float | Scale by which to enlarge the entire diagram by | 15 |
100+
| linewidth | float | Width of drawn lines | 2 |
101+
| color | str | Default color for everything | 'black' |
102+
| offset_scale | float | How far to offset the label from the center of the component. Relative to the global scale option. | 1 |
103+
| font | str | Text font for labels | 'monospace' |
104+
| value | str | Inductance in henries | (required) |
105+
| current | str | Maximum current rating in amps | (no value) |
106+
107+
## Component `:RESISTOR`
108+
109+
Reference Designators: `R`, `VR`, `RV`
110+
111+
| Option | Value | Description | Default |
112+
|:------:|:-----:|:------------|:-------:|
113+
| scale | float | Scale by which to enlarge the entire diagram by | 15 |
114+
| linewidth | float | Width of drawn lines | 2 |
115+
| color | str | Default color for everything | 'black' |
116+
| offset_scale | float | How far to offset the label from the center of the component. Relative to the global scale option. | 1 |
117+
| font | str | Text font for labels | 'monospace' |
118+
| value | str | Resistance in ohms | (required) |
119+
| power | str | Maximum power dissipation in watts (i.e. size of the resistor) | (no value) |

‎scripts/docs.py

Lines changed: 66 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,74 @@
11
#! /usr/bin/env python3
2-
import re
2+
import datetime
33
import os
4-
from itertools import groupby
5-
6-
raise NotImplementedError("TODO: re-write docs generator script "
7-
"after I re-do the cmdline help text")
8-
9-
TOP = ("# Supported Schemascii Components\n\n<!--\n"
10-
+ "".join(reversed("/stpircs nur dna\nyp.redner_stnenopmoc/iicsa"
11-
"mehcs ni sgnirtscod eht tide ,daetsnI\n"
12-
".nettirwrevo eb ylpmis "
13-
"lliw segnahc ruoY\n!TIDE TON OD\n!ELIF"
14-
" DETARENEG YLLACITAMOTUA"))
15-
+ os.path.basename(__file__)
16-
+ "".join(reversed(".elif siht etareneg-er ot "))
17-
+ "\n-->\n\n| Reference Designators | Description | "
18-
+ "BOM Syntax | Supported Flags |"
19-
+ "\n|:--:|:--|:--:|:--|\n")
20-
21-
22-
def group_components_by_func():
23-
items = groupby(list(RENDERERS.items()), lambda x: x[1])
24-
out = {}
25-
for x, g in items:
26-
out[x] = [p[0] for p in g]
27-
return out
28-
29-
30-
def parse_docstring(d):
31-
out = [None, None, None]
32-
if fs := re.search(r"flags:(.*?)$", d, re.M):
33-
out[2] = [f.split("=") for f in fs.group(1).split(",")]
34-
d = d.replace(fs.group(), "")
35-
if b := re.search(r"bom:(.*?)$", d, re.M):
36-
out[1] = b.group(1)
37-
d = d.replace(b.group(), "")
38-
out[0] = d.strip()
39-
return out
4+
import textwrap
5+
6+
from scriptutils import spit, spy
7+
8+
# flake8: noqa: E402
9+
10+
from schemascii.component import Component
11+
from schemascii.data import Data
12+
from schemascii.data_consumer import _NOT_SET as NO_DEFAULT
13+
from schemascii.data_consumer import Option
14+
15+
16+
def output_file(filename: os.PathLike, heading: str, content: str):
17+
spit(filename, textwrap.dedent(f"""
18+
# {heading}
19+
20+
<!-- This file was automatically generated by scripts/docs.py
21+
on {datetime.datetime.now().ctime()} -->
22+
""") + content)
23+
24+
25+
def format_option(opt: Option) -> str:
26+
typename = (opt.type.__name__
27+
if isinstance(opt.type, type)
28+
else " or ".join(f"`{z!s}`" for z in opt.type))
29+
items: list[str] = [opt.name, typename, opt.help, "(required)"]
30+
if opt.default is not NO_DEFAULT:
31+
items[-1] = repr(opt.default) if opt.default is not None else "(no value)"
32+
return f"| {' | '.join(items)} |\n"
33+
34+
35+
def format_scope(scopename: str, options: list[Option],
36+
interj: str, head: str) -> str:
37+
scope_text = textwrap.dedent(f"""
38+
## {head} `{scopename.upper()}`%%%INTERJ%%%
39+
40+
| Option | Value | Description | Default |
41+
|:------:|:-----:|:------------|:-------:|
42+
""")
43+
for option in options:
44+
scope_text += format_option(option)
45+
scope_text = scope_text.replace("%%%INTERJ%%%", "\n\n" + interj if interj else "")
46+
return scope_text
47+
48+
49+
def get_RDs(scopename: str) -> list[str] | None:
50+
out = []
51+
tgt_list = Data.available_options[scopename]
52+
for component in Component.all_components:
53+
if Component.all_components[component].options == tgt_list:
54+
out.append(component)
55+
if out:
56+
return out
57+
return None
4058

4159

4260
def main():
43-
content = TOP
44-
for func, rds in group_components_by_func().items():
45-
data = parse_docstring(func.__doc__)
46-
content += "| " + ", ".join(f"`{x}`" for x in rds) + " | "
47-
content += dat F438 a[0].replace("\n", "<br>") + " | "
48-
content += "`" + data[1] + "` | "
49-
content += "<br>".join(f"`{x[0]}` = {x[1]}" for x in (data[2] or []))
50-
content += " |\n"
51-
with open("supported-components.md", "w") as f:
52-
f.write(content)
61+
content = ""
62+
for s, d in Data.available_options.items():
63+
rds_line = ""
64+
heading = "Scope"
65+
if (rds := get_RDs(s)) is not None:
66+
heading = "Component"
67+
rds_line = "Reference Designators: "
68+
rds_line += ", ".join(f"`{x}`" for x in rds)
69+
content += format_scope(s, d, rds_line, heading)
70+
71+
output_file("options.md", "Data Section Options", content)
5372

5473

5574
if __name__ == '__main__':

‎scripts/release.py

Lines changed: 2 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,11 @@
11
#! /usr/bin/env python3
22
import argparse
3-
import os
43
import re
54
import sys
65

7-
# pylint: disable=unspecified-encoding,missing-function-docstring
8-
9-
10-
def cmd(sh_line):
11-
print(sh_line)
12-
if code := os.system(sh_line):
13-
print("*** Error", code, file=sys.stderr)
14-
sys.exit(code)
15-
16-
17-
def slurp(file):
18-
with open(file) as f:
19-
return f.read()
20-
21-
22-
def spit(file, text):
23-
with open(file, "w") as f:
24-
f.write(text)
6+
from scriptutils import cmd, slurp, spit
257

8+
# pylint: disable=unspecified-encoding
269

2710
a = argparse.ArgumentParser()
2811
a.add_argument("version", help="release tag")

‎scripts/scriptutils.py

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
import os
2+
import sys
3+
import typing
4+
5+
# pylint: disable=missing-function-docstring
6+
7+
T = typing.TypeVar("T")
8+
9+
10+
def cmd(sh_line: str, say: bool = True):
11+
if say:
12+
print(sh_line)
13+
if code := os.system(sh_line):
14+
print("*** Error", code, file=sys.stderr)
15+
sys.exit(code)
16+
17+
18+
def slurp(file: os.PathLike) -> str:
19+
with open(file) as f:
20+
return f.read()
21+
22+
23+
def spit(file: os.PathLike, text: str):
24+
with open(file, "w") as f:
25+
f.write(text)
26+
27+
28+
def spy(value: T 55F0 ) -> T:
29+
print(value)
30+
return value

‎supported-components.md

Lines changed: 0 additions & 22 deletions
This file was deleted.

0 commit comments

Comments
 (0)
0