forked from esphome/esphome-docs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
schema_doc.py
1210 lines (1028 loc) · 44.9 KB
/
schema_doc.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
from genericpath import exists
import re
import json
import urllib
from typing import MutableMapping
from sphinx.util import logging
from docutils import nodes
# Instructions for building
# you must have checked out this project in the same folder of
# esphome and esphome-vscode so the SCHEMA_PATH below can find the source schemas
# This file is not processed by default as extension unless added.
# To add this extension from command line use:
# -Dextensions=github,seo,sitemap,components,schema_doc"
# also for improve performance running old version
# -d_build/.doctrees-schema
# will put caches in another dir and not overwrite the ones without schema
SCHEMA_PATH = "../esphome-vscode/server/src/schema/"
CONFIGURATION_VARIABLES = "Configuration variables:"
CONFIGURATION_OPTIONS = "Configuration options:"
PIN_CONFIGURATION_VARIABLES = "Pin configuration variables:"
COMPONENT_HUB = "Component/Hub"
JSON_DUMP_PRETTY = True
class Statistics:
props_documented = 0
enums_good = 0
enums_bad = 0
statistics = Statistics()
logger = logging.getLogger(__name__)
def setup(app):
import os
if not os.path.isfile(SCHEMA_PATH + "esphome.json"):
logger.info(f"{SCHEMA_PATH} not found. Not documenting schema.")
return
app.connect("doctree-resolved", doctree_resolved)
app.connect("build-finished", build_finished)
app.files = {}
return {"version": "1.0.0", "parallel_read_safe": True, "parallel_write_safe": True}
def find_platform_component(app, platform, component):
file_data = get_component_file(app, component)
return file_data[f"{component}.{platform}"]["schemas"]["CONFIG_SCHEMA"]
def doctree_resolved(app, doctree, docname):
if docname == "components/index":
# nothing useful here
return
handle_component(app, doctree, docname)
PLATFORMS_TITLES = {
"Sensor": "sensor",
"Binary Sensor": "binary_sensor",
"Text Sensor": "text_sensor",
"Output": "output",
"Cover": "cover",
"Button": "button",
"Select": "select",
"Fan": "fan",
"Lock": "lock",
"Number": "number",
"Climate": "climate",
"CAN Bus": "canbus",
"Stepper": "stepper",
"Switch": "switch",
"I²C": "i2c",
}
CUSTOM_DOCS = {
"guides/automations": {
"Global Variables": "globals.schemas.CONFIG_SCHEMA",
},
"guides/configuration-types": {
"Pin Schema": [
"esp32.pin.schema",
"esp8266.pin.schema",
],
},
"components/binary_sensor/index": {
"Binary Sensor Filters": "binary_sensor.registry.filter",
},
"components/canbus": {
"_LoadSchema": False,
"Base CAN Bus Configuration": "canbus.schemas.CANBUS_SCHEMA",
},
"components/climate/climate_ir": {"_LoadSchema": False, "IR Remote Climate": []},
"components/display/index": {
"Images": "image.schemas.CONFIG_SCHEMA",
"Fonts": "font.schemas.CONFIG_SCHEMA",
"Color": "color.schemas.CONFIG_SCHEMA",
"Animation": "animation.schemas.CONFIG_SCHEMA",
},
"components/light/index": {
"Base Light Configuration": [
"light.schemas.ADDRESSABLE_LIGHT_SCHEMA",
"light.schemas.BINARY_LIGHT_SCHEMA",
"light.schemas.BRIGHTNESS_ONLY_LIGHT_SCHEMA",
"light.schemas.LIGHT_SCHEMA",
],
"Light Effects": "light.registry.effects",
},
"components/light/fastled": {
"_LoadSchema": False,
"Clockless": "fastled_clockless.platform.light.schemas.CONFIG_SCHEMA",
"SPI": "fastled_spi.platform.light.schemas.CONFIG_SCHEMA",
},
"components/binary_sensor/ttp229": {
"_LoadSchema": False,
},
"components/mcp230xx": {
"_LoadSchema": False,
PIN_CONFIGURATION_VARIABLES: "mcp23xxx.pin",
},
"components/mqtt": {
"MQTT Component Base Configuration": "core.schemas.MQTT_COMMAND_COMPONENT_SCHEMA",
"MQTTMessage": "mqtt.schemas.MQTT_MESSAGE_BASE",
},
"components/output/index": {
"Base Output Configuration": "output.schemas.FLOAT_OUTPUT_SCHEMA",
},
"components/remote_transmitter": {
"Remote Transmitter Actions": "remote_base.schemas.BASE_REMOTE_TRANSMITTER_SCHEMA",
},
"components/sensor/index": {
"Sensor Filters": "sensor.registry.filter",
},
"components/time": {
"_LoadSchema": False,
"Base Time Configuration": "time.schemas.TIME_SCHEMA",
"on_time Trigger": "time.schemas.TIME_SCHEMA.schema.config_vars.on_time.schema",
"Home Assistant Time Source": "homeassistant.platform.time.schemas.CONFIG_SCHEMA",
"SNTP Time Source": "sntp.platform.time.schemas.CONFIG_SCHEMA",
"GPS Time Source": "gps.platform.time.schemas.CONFIG_SCHEMA",
"DS1307 Time Source": "ds1307.platform.time.schemas.CONFIG_SCHEMA",
},
"components/wifi": {
"Connecting to Multiple Networks": "wifi.schemas.CONFIG_SCHEMA.schema.config_vars.networks.schema",
"Enterprise Authentication": "wifi.schemas.EAP_AUTH_SCHEMA",
},
"custom/custom_component": {
"Generic Custom Component": "custom_component.schemas.CONFIG_SCHEMA"
},
"components/esp32": {
"Arduino framework": "esp32.schemas.CONFIG_SCHEMA.schema.config_vars.framework.types.arduino",
"ESP-IDF framework": "esp32.schemas.CONFIG_SCHEMA.schema.config_vars.framework.types.esp-idf",
},
"components/sensor/airthings_ble": {
"_LoadSchema": False,
},
"components/sensor/radon_eye_ble": {
"_LoadSchema": False,
},
"components/sensor/xiaomi_ble": {
"_LoadSchema": False,
},
"components/sensor/xiaomi_miscale2": {
"_LoadSchema": False,
},
"components/mcp23Sxx": {
"_LoadSchema": False,
},
"components/display/lcd_display": {"_LoadSchema": False},
"components/display/ssd1306": {"_LoadSchema": False},
"components/display/ssd1322": {"_LoadSchema": False},
"components/display/ssd1325": {"_LoadSchema": False},
"components/display/ssd1327": {"_LoadSchema": False},
"components/display/ssd1351": {"_LoadSchema": False},
"components/copy": {"_LoadSchema": False},
}
def get_node_title(node):
return list(node.traverse(nodes.title))[0].astext()
def read_file(fileName):
f = open(SCHEMA_PATH + fileName + ".json", "r", encoding="utf-8-sig")
str = f.read()
return json.loads(str)
def is_config_vars_title(title_text):
return title_text == CONFIGURATION_VARIABLES or title_text == CONFIGURATION_OPTIONS
class SchemaGeneratorVisitor(nodes.NodeVisitor):
def __init__(self, app, doctree, docname):
nodes.NodeVisitor.__init__(self, doctree)
self.app = app
self.doctree = doctree
self.docname = docname
self.path = docname.split("/")
self.json_component = None
self.props = None
self.platform = None
self.json_platform_component = None
self.title_id = None
self.props_section_title = None
self.find_registry = None
self.component = None
self.section_level = 0
self.file_schema = None
self.custom_doc = CUSTOM_DOCS.get(docname)
if self.path[0] == "components":
if len(self.path) == 2: # root component, e.g. dfplayer, logger
self.component = docname[11:]
if not self.custom_doc or self.custom_doc.get("_LoadSchema", True):
self.file_schema = get_component_file(app, self.component)
self.json_component = self.file_schema[self.component]["schemas"][
"CONFIG_SCHEMA"
]
else: # sub component, e.g. output/esp8266_pwm
# components here might have a core / hub, eg. dallas, ads1115
# and then they can be a binary_sensor, sensor, etc.
self.platform = self.path[1]
self.component = self.path[2]
if self.component == "ssd1331":
self.component = "ssd1331_spi"
if not self.custom_doc or self.custom_doc.get("_LoadSchema", True):
if self.component == "index":
# these are e.g. sensor, binary sensor etc.
self.component = self.platform.replace(" ", "_").lower()
self.file_schema = get_component_file(app, self.component)
self.json_component = self.file_schema[self.component][
"schemas"
].get(self.component.upper() + "_SCHEMA")
pass
else:
self.json_component = get_component_file(app, self.component)
self.json_platform_component = find_platform_component(
app, self.platform, self.component
)
self.previous_title_text = "No title"
self.is_component_hub = False
# used in custom_docs when titles are mapped to array of components, this
# allows for same configuration text be applied to different json schemas
self.multi_component = None
# a stack for props, used when there are nested props to save high level props.
self.prop_stack = []
# The prop just filled in, used when there are nested props and need to know which
# want to dig
self.current_prop = None
# self.filled_props used to know when any prop is added to props,
# we dont invalidate props on exiting bullet lists but just when entering a new title
self.filled_props = False
# Found a Configuration variables: heading, this is to increase docs consistency
self.accept_props = False
self.bullet_list_level = 0
def set_component_description(self, description, componentName, platformName=None):
if platformName is not None:
platform = get_component_file(self.app, platformName)
platform[platformName]["components"][componentName.lower()][
"docs"
] = description
else:
core = get_component_file(self.app, "esphome")["core"]
if componentName in core["components"]:
core["components"][componentName]["docs"] = description
elif componentName in core["platforms"]:
core["platforms"][componentName]["docs"] = description
else:
raise ValueError(
"Cannot set description for component " + componentName
)
def visit_document(self, node):
# ESPHome page docs follows strict formatting guidelines which allows
# for docs to be parsed directly into yaml schema
if self.docname in ["components/sensor/binary_sensor_map"]:
# temporarily not supported
raise nodes.SkipChildren
if self.docname in ["components/climate/climate_ir"]:
# not much to do on the visit to the document, component will be found by title
return
if len(list(node.traverse(nodes.paragraph))) == 0:
# this is empty, not much to do
raise nodes.SkipChildren
self.props_section_title = get_node_title(node)
# Document first paragraph is description of this thing
description = self.getMarkdownParagraph(node)
if self.json_platform_component:
self.set_component_description(description, self.component, self.platform)
elif self.json_component:
self.set_component_description(description, self.component)
# for most components / platforms get the props, this allows for a less restrictive
# first title on the page
if self.json_component or self.json_platform_component:
if is_component_file(
self.app,
self.component,
):
self.props = self.find_props(
self.json_platform_component
if self.json_platform_component
else self.json_component,
True,
)
def visit_table(self, node):
if (
self.docname == "components/climate/climate_ir"
and len(CUSTOM_DOCS["components/climate/climate_ir"]["IR Remote Climate"])
== 0
):
# figure out multi components from table
table_rows = node[0][4]
for row in table_rows:
components_paths = [
components + ".platform.climate.schemas.CONFIG_SCHEMA"
for components in row[1].astext().split("\n")
]
CUSTOM_DOCS["components/climate/climate_ir"][
"IR Remote Climate"
] += components_paths
def depart_document(self, node):
pass
def visit_section(self, node):
self.section_level += 1
section_title = get_node_title(node)
if self.custom_doc and section_title in self.custom_doc:
r = self.custom_doc[section_title]
if ".registry." in r:
self.find_registry = r
def depart_section(self, node):
self.section_level -= 1
if self.section_level == 1:
self.find_registry = None
def unknown_visit(self, node):
pass
def unknown_departure(self, node):
pass
def visit_title(self, node):
title_text = node.astext()
if self.custom_doc is not None and title_text in self.custom_doc:
if isinstance(self.custom_doc[title_text], list):
self.multi_component = self.custom_doc[title_text]
self.filled_props = False
self.props = None
desc = self.getMarkdownParagraph(node.parent)
for c in self.multi_component:
if len(c.split(".")) == 2:
self.set_component_description(desc, c.split(".")[0])
return
json_component = self.find_component(self.custom_doc[title_text])
if not json_component:
return
if self.json_component is None:
self.json_component = json_component
parts = self.custom_doc[title_text].split(".")
if parts[0] not in ["core", "remote_base"] and parts[-1] != "pin":
if parts[1] == "platform":
self.set_component_description(
self.getMarkdownParagraph(node.parent), parts[0], parts[2]
)
else:
self.set_component_description(
self.getMarkdownParagraph(node.parent),
parts[0],
)
self.props_section_title = title_text
self.props = self.find_props(json_component)
return
elif title_text == COMPONENT_HUB:
# here comes docs for the component, make sure we have props of the component
# Needed for e.g. ads1115
self.props_section_title = f"{self.path[-1]} {title_text}"
json_component = self.get_component_schema(
self.path[-1] + ".CONFIG_SCHEMA"
).get("schema", {})
if json_component:
self.props = self.find_props(json_component)
self.set_component_description(
self.getMarkdownParagraph(node.parent), self.path[-1]
)
# mark this to retrieve components instead of platforms
self.is_component_hub = True
elif is_config_vars_title(title_text):
if not self.props and self.multi_component is None:
raise ValueError(
f'Found a "{title_text}": title after {self.previous_title_text}. Unknown object.'
)
elif title_text == "Over SPI" or title_text == "Over I²C":
suffix = "_spi" if "SPI" in title_text else "_i2c"
# these could be platform components, like the display's ssd1306
# but also there are components which are component/hub
# and there are non platform components with the SPI/I2C versions,
# like pn532, those need to be marked with the 'Component/Hub' title
component = self.path[-1] + suffix
self.props_section_title = self.path[-1] + " " + title_text
if self.platform is not None and not self.is_component_hub:
json_platform_component = find_platform_component(
self.app, self.platform, component
)
if not json_platform_component:
raise ValueError(
f"Cannot find platform {self.platform} component '{component}' after found title: '{title_text}'."
)
self.props = self.find_props(json_platform_component)
# Document first paragraph is description of this thing
json_platform_component["docs"] = self.getMarkdownParagraph(node.parent)
else:
json_component = self.get_component_schema(
component + ".CONFIG_SCHEMA"
).get("schema", {})
if not json_component:
raise ValueError(
f"Cannot find component '{component}' after found title: '{title_text}'."
)
self.props = self.find_props(json_component)
# Document first paragraph is description of this thing
self.set_component_description(
self.getMarkdownParagraph(node.parent), component
)
# Title is description of platform component, those ends with Sensor, Binary Sensor, Cover, etc.
elif (
len(
list(
filter(
lambda x: title_text.endswith(x), list(PLATFORMS_TITLES.keys())
)
)
)
> 0
):
if title_text in PLATFORMS_TITLES:
# this omits the name of the component, but we know the platform
platform_name = PLATFORMS_TITLES[title_text]
if self.path[-1] == "index":
component_name = self.path[-2]
else:
component_name = self.path[-1]
self.props_section_title = component_name + " " + title_text
else:
# # title first word is the component name
# component_name = title_text.split(" ")[0]
# # and the rest is the platform
# platform_name = PLATFORMS_TITLES.get(
# title_text[len(component_name) + 1 :]
# )
# if not platform_name:
# # Some general title which does not locate a component directly
# return
# self.props_section_title = title_text
for t in PLATFORMS_TITLES:
if title_text.endswith(t):
component_name = title_text[
0 : len(title_text) - len(t) - 1
].replace(" ", "_")
platform_name = PLATFORMS_TITLES[t]
if not platform_name:
# Some general title which does not locate a component directly
return
self.props_section_title = title_text
if not is_component_file(self.app, component_name):
return
c = find_platform_component(self.app, platform_name, component_name.lower())
if c:
self.json_platform_component = c
self.set_component_description(
self.getMarkdownParagraph(node.parent),
component_name,
platform_name,
)
# Now fill props for the platform element
try:
self.props = self.find_props(self.json_platform_component)
except KeyError:
raise ValueError("Cannot find platform props")
elif title_text.endswith("Component") or title_text.endswith("Bus"):
# if len(path) == 3 and path[2] == 'index':
# # skip platforms index, e.g. sensors/index
# continue
split_text = title_text.split(" ")
self.props_section_title = title_text
# some components are several components in a single platform doc
# e.g. ttp229 binary_sensor has two different named components.
component_name = (
"_".join(split_text[:-1]).lower().replace(".", "").replace("i²c", "i2c")
)
if component_name != self.platform and is_component_file(
self.app, component_name
):
f = get_component_file(self.app, component_name)
# Document first paragraph is description of this thing
description = self.getMarkdownParagraph(node.parent)
if component_name in f:
self.set_component_description(description, component_name)
c = f[component_name]
if c:
self.json_component = c["schemas"]["CONFIG_SCHEMA"]
try:
self.props = self.find_props(self.json_component)
self.multi_component = None
except KeyError:
raise ValueError(
"Cannot find props for component " + component_name
)
return
# component which are platforms in doc, used by: stepper and canbus, lcd_pcf8574
elif f"{component_name}.{self.path[1]}" in f:
self.set_component_description(
description, component_name, self.path[1]
)
self.json_platform_component = f[
f"{component_name}.{self.path[1]}"
]["schemas"]["CONFIG_SCHEMA"]
try:
self.props = self.find_props(self.json_platform_component)
except KeyError:
raise ValueError(
f"Cannot find props for platform {self.path[1]} component {self.component_name}"
)
return
elif title_text.endswith("Trigger"):
# Document first paragraph is description of this thing
description = self.getMarkdownParagraph(node.parent)
split_text = title_text.split(" ")
if len(split_text) != 2:
return
key = split_text[0]
if (
not self.props or not self.props.typed
): # props are right for typed components so far
c = self.json_component
if c:
trigger_schema = self.find_props(c).get(key)
if trigger_schema is not None:
self.props = self.find_props(trigger_schema)
self.props_section_title = title_text
elif title_text == PIN_CONFIGURATION_VARIABLES:
self.component = self.find_component(self.path[-1] + ".pin")
self.props = self.find_props(self.component)
self.accept_props = True
if not self.component:
raise ValueError(
f'Found a "{PIN_CONFIGURATION_VARIABLES}" entry but could not find pin schema'
)
elif title_text.endswith("Action") or title_text.endswith("Condition"):
# Document first paragraph is description of this thing
description = self.getMarkdownParagraph(node.parent)
split_text = title_text.split(" ")
if len(split_text) != 2:
return
key = split_text[0]
component_parts = split_text[0].split(".")
if len(component_parts) == 3:
cv = get_component_file(self.app, component_parts[1])[
component_parts[1] + "." + component_parts[0]
][split_text[1].lower()][component_parts[2]]
if cv is not None:
cv["docs"] = description
self.props = self.find_props(cv.get("schema", {}))
elif len(component_parts) == 2:
registry_name = ".".join(
[component_parts[0], "registry", split_text[1].lower()]
)
key = component_parts[1]
self.find_registry_prop(registry_name, key, description)
else:
registry_name = f"core.registry.{split_text[1].lower()}"
# f"automation.{split_text[1].upper()}_REGISTRY"
self.find_registry_prop(registry_name, key, description)
if self.section_level == 3 and self.find_registry:
name = title_text
if name.endswith(" Effect"):
name = title_text[: -len(" Effect")]
if name.endswith(" Light"):
name = name[: -len(" Light")]
key = name.replace(" ", "_").replace(".", "").lower()
description = self.getMarkdownParagraph(node.parent)
self.find_registry_prop(self.find_registry, key, description)
self.props_section_title = title_text
def get_component_schema(self, name):
parts = name.split(".")
schema_file = get_component_file(self.app, parts[0])
if parts[1] == "registry":
schema = schema_file.get(parts[0], {}).get(parts[2], {})
elif len(parts) == 3:
schema = (
schema_file.get(f"{parts[0]}.{parts[1]}")
.get("schemas", {})
.get(parts[2], {})
)
else:
schema = schema_file.get(parts[0], {}).get("schemas", {}).get(parts[1], {})
return schema
def get_component_config_var(self, name, key):
c = self.get_component_schema(name)
if key in c:
return c[key]
if "config_vars" not in c:
return c
if key in c["config_vars"]:
return c["config_vars"][c]
def find_registry_prop(self, registry_name, key, description):
c = self.get_component_schema(registry_name)
if key in c:
cv = c[key]
if cv is not None:
cv["docs"] = description
self.props = self.find_props(cv.get("schema", {}))
def depart_title(self, node):
if self.filled_props:
self.filled_props = False
self.props = None
self.current_prop = None
self.accept_props = False
self.multi_component = None
self.previous_title_text = node.astext()
self.title_id = node.parent["ids"][0]
def find_props_previous_title(self):
comp = self.json_component or self.json_platform_component
if comp:
props = self.find_props(comp)
if self.previous_title_text in props:
prop = props[self.previous_title_text]
if prop:
self.props = self.find_props(prop)
else:
# return fake dict so better errors are printed
self.props = {"__": "none"}
def visit_Text(self, node):
if self.multi_component:
return
if is_config_vars_title(node.astext()):
if not self.props:
self.find_props_previous_title()
if not self.props:
raise ValueError(
f'Found a "{node.astext()}" entry for unknown object after {self.previous_title_text}'
)
self.accept_props = True
raise nodes.SkipChildren
def depart_Text(self, node):
pass
def visit_paragraph(self, node):
if is_config_vars_title(node.astext()):
if not self.props and not self.multi_component:
self.find_props_previous_title()
if not self.props and not self.multi_component:
logger.info(
f"In {self.docname} / {self.previous_title_text} found a {node.astext()} title and there are no props."
)
# raise ValueError(
# f'Found a "{node.astext()}" entry for unknown object after {self.previous_title_text}'
# )
self.accept_props = True
raise nodes.SkipChildren
def depart_paragraph(self, node):
pass
def visit_bullet_list(self, node):
self.bullet_list_level = self.bullet_list_level + 1
if (
self.current_prop
and (self.props or self.multi_component)
and self.bullet_list_level > 1
):
self.prop_stack.append((self.current_prop, node))
self.accept_props = True
return
if not self.props and self.multi_component is None:
raise nodes.SkipChildren
def depart_bullet_list(self, node):
self.bullet_list_level = self.bullet_list_level - 1
if len(self.prop_stack) > 0:
stack_prop, stack_node = self.prop_stack[-1]
if stack_node == node:
self.prop_stack.pop()
self.filled_props = True
self.current_prop = stack_prop
def visit_list_item(self, node):
if self.accept_props and self.props:
self.filled_props = True
self.current_prop, found = self.update_prop(node, self.props)
if self.current_prop and not found:
logger.info(
f"In '{self.docname} {self.previous_title_text} Cannot find property {self.current_prop}"
)
elif self.multi_component:
# update prop for each component
found_any = False
self.current_prop = None
for c in self.multi_component:
props = self.find_props(self.find_component(c))
self.current_prop, found = self.update_prop(node, props)
if self.current_prop and found:
found_any = True
if self.current_prop and not found_any:
logger.info(
f"In '{self.docname} {self.previous_title_text} Cannot find property {self.current_prop}"
)
self.filled_props = True
def depart_list_item(self, node):
pass
def visit_literal(self, node):
raise nodes.SkipChildren
def depart_literal(self, node):
pass
def getMarkdown(self, node):
from markdown import Translator
t = Translator(
urllib.parse.urljoin(self.app.config.html_baseurl, self.docname + ".html"),
self.doctree,
)
node.walkabout(t)
return t.output.strip("\n")
def getMarkdownParagraph(self, node):
paragraph = list(node.traverse(nodes.paragraph))[0]
markdown = self.getMarkdown(paragraph)
param_type = None
# Check if there is type information for this item
try:
name_type = markdown[: markdown.index(": ") + 2]
ntr = re.search(
r"(\(((\*\*Required\*\*)|(\*Optional\*))(,\s(.*))*)\):\s",
name_type,
re.IGNORECASE,
)
if ntr:
param_type = ntr.group(6)
if param_type:
markdown = (
f"**{param_type}**: {markdown[markdown.index(': ') + 2 :]}"
)
except ValueError:
# ': ' not found
pass
title = list(node.traverse(nodes.title))[0]
if len(title) > 0:
url = urllib.parse.urljoin(
self.app.config.html_baseurl,
self.docname + ".html#" + title.parent["ids"][0],
)
if (
self.props_section_title is not None
and self.props_section_title.endswith(title.astext())
):
markdown += f"\n\n*See also: [{self.props_section_title}]({url})*"
else:
markdown += f"\n\n*See also: [{self.getMarkdown(title)}]({url})*"
return markdown
def update_prop(self, node, props):
prop_name = None
for s_prop, n in self.prop_stack:
inner = props.get(s_prop)
if inner is not None and "schema" in inner:
props = self.Props(self, inner["schema"])
elif inner is not None and inner.get("type") == "typed":
# this is used in external_components
props = self.Props(self, inner)
elif inner is not None and inner.get("type") == "enum":
enum_raw = self.getMarkdown(node)
# the regex allow the format to have either a ":" or a " -" as the value / docs separator, value must be in `back ticks`
# also description is optional
enum_match = re.search(
r"\* `([^`]*)`((:| -) (.*))*", enum_raw, re.IGNORECASE
)
if enum_match:
enum_value = enum_match.group(1)
enum_docs = enum_match.group(4)
found = False
for name in inner["values"]:
if enum_value.upper().replace(" ", "_") == str(name).upper():
found = True
if enum_docs:
enum_docs = enum_docs.strip()
if "values_docs" not in inner:
inner["values_docs"] = {name: enum_docs}
else:
inner["values_docs"][name] = enum_docs
statistics.props_documented += 1
statistics.enums_good += 1
if not found:
logger.info(
f"In '{self.docname} {self.previous_title_text} Property {s_prop} cannot find enum value {enum_value}"
)
else:
statistics.enums_bad += 1
logger.info(
f"In '{self.docname} {self.previous_title_text} Property {s_prop} unexpected enum member description format"
)
else:
# nothing to do?
return prop_name, False
raw = node.rawsource # this has the full raw rst code for this property
if not raw.startswith("**"):
# not bolded, most likely not a property definition,
# usually texts like 'All properties from...' etc
return prop_name, False
markdown = self.getMarkdown(node)
markdown += f"\n\n*See also: [{self.props_section_title}]({urllib.parse.urljoin(self.app.config.html_baseurl, self.docname +'.html#'+self.title_id)})*"
try:
name_type = markdown[: markdown.index(": ") + 2]
except ValueError:
logger.info(
f"In '{self.docname} {self.previous_title_text} Property format error. Missing ': ' in {raw}'"
)
return prop_name, False
# Example properties formats are:
# **name** (**Required**, string): Long Description...
# **name** (*Optional*, string): Long Description... Defaults to ``value``.
# **name** (*Optional*): Long Description... Defaults to ``value``.
ntr = re.search(
r"\* \*\*(\w*)\*\*\s(\(((\*\*Required\*\*)|(\*Optional\*))(,\s(.*))*)\):\s",
name_type,
re.IGNORECASE,
)
if ntr:
prop_name = ntr.group(1)
param_type = ntr.group(7)
else:
s2 = re.search(
r"\* \*\*(\w*)\*\*\s(\(((\*\*Required\*\*)|(\*Optional\*))(,\s(.*))*)\):\s",
markdown,
re.IGNORECASE,
)
if s2:
# this is e.g. when a property has a list inside, and the list inside are the options.
# just validate **prop_name**
s3 = re.search(r"\* \*\*(\w*)\*\*:\s", name_type)
prop_name = s3.group(1)
param_type = None
else:
logger.info(
f"In '{self.docname} {self.previous_title_text} Invalid property format: {node.rawsource}"
)
return prop_name, False
k = str(prop_name)
config_var = props.get(k)
if not config_var:
# Create docs for common properties when descriptions are overridden
# in the most specific component.
if k in [
"id",
"name",
"internal",
# i2c
"address",
"i2c_id",
# polling component
"update_interval",
# uart
"uart_id",
# light
"effects",
"gamma_correct",
"default_transition_length",
"flash_transition_length",
"color_correct",
# display
"lambda",
"pages",
"rotation",
# spi
"spi_id",
"cs_pin",
# output (binary/float output)
"inverted",
"power_supply",
# climate
"receiver_id",
]:
config_var = props[k] = {}
else:
if self.path[1] == "esphome" and k in [
# deprecated esphome
"platform",
"board",
"arduino_version",
"esp8266_restore_from_flash",
]:
return prop_name, True
return prop_name, False
desc = markdown[markdown.index(": ") + 2 :].strip()
if param_type:
desc = "**" + param_type + "**: " + desc
config_var["docs"] = desc