move lg-arc4.md content to docstrings

[joe-p]

This is a draft PR showing what moving existing documentation to docstrings would look like. The main idea is that all of the conceptual documentation will be hosted on the new devportal, thus making a lot of the conceptual content redundant. The goal is to make docs easier to maintain and to provide more context in docstrings where applicable.

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
src/puya_lib
arc4.py	126	126	0%	1–332
bytes.py	9	9	0%	1–15
util.py	16	16	0%	1–33
src/puya
__main__.py	34	34	0%	1–57
arc32.py	71	2	97%	78, 104
arc56.py	78	2	97%	279, 285
artifact_sorter.py	53	1	98%	84
compile.py	161	8	95%	92–93, 135–138, 158–161, 321, 369
context.py	31	1	97%	35
errors.py	35	8	77%	40–42, 44–46, 50–51
log.py	235	61	74%	26–29, 45–48, 82, 92–93, 98–105, 120–128, 150, 184–185, 227–229, 232–234, 236, 249–258, 283, 289, 294, 363–364, 373, 401–403, 416–430
main.py	36	36	0%	1–49
parse.py	87	5	94%	31, 40, 50, 56, 87
utils.py	201	18	91%	50, 67–68, 77–78, 86–87, 177, 195–197, 204, 212, 226, 249, 251, 274, 309
src/puya/awst
function_traverser.py	292	3	99%	76, 372, 378
nodes.py	995	40	96%	100, 104–107, 147, 151–154, 365, 561, 577, 611, 652, 681–682, 732, 759–760, 908, 930, 962, 988, 993, 1148, 1233, 1249, 1298, 1375, 1456, 1510, 1514, 1637, 1782, 1787, 1792, 1800, 1805, 1810
serialize.py	68	11	84%	24, 84–89, 95–98
to_code_visitor.py	434	12	97%	131, 242, 279, 325, 579, 586–589, 619, 647, 651
txn_fields.py	98	1	99%	48
wtypes.py	330	18	95%	174, 178–181, 195–196, 200, 230, 243, 254, 259–260, 294, 332, 346, 396, 519
src/puya/awst/validation
arc4_copy.py	113	1	99%	38
base_invoker.py	47	4	91%	55, 62, 72–76
immutable.py	31	2	94%	26, 34
inner_transactions.py	187	1	99%	161
labels.py	30	8	73%	25–27, 32, 36–41
scratch_slots.py	38	4	89%	18, 32, 47, 49
src/puya/ir
arc4_router.py	281	19	93%	100, 163, 219, 299, 347, 419, 432, 490–491, 503, 508, 513, 518, 523, 528, 548–552, 685, 722
avm_ops.py	323	1	99%	46
avm_ops_models.py	50	3	94%	21, 30, 38
context.py	101	8	92%	68, 75, 78, 80, 118–119, 129, 135
main.py	392	14	96%	80–86, 96–102, 128, 141, 169, 551, 784–788
models.py	531	22	96%	75, 183, 190, 339, 410–411, 416, 422–426, 439, 483, 512, 568, 614, 694, 710, 751, 754, 761, 764, 853–854
ssa.py	130	3	98%	51–52, 150
to_text_visitor.py	152	7	95%	123, 212, 219–224
types_.py	101	10	90%	50, 57, 91–95, 116, 152, 157–159
visitor.py	129	17	87%	145, 193, 205, 220, 223, 236, 239, 245, 248, 259, 262, 265, 268, 271, 274, 277, 280
visitor_mutator.py	105	2	98%	174–175
vla.py	72	1	99%	87
src/puya/ir/builder
_utils.py	136	5	96%	229–231, 293–300
arc4.py	500	21	96%	175–180, 479, 482, 540–543, 815–816, 1062, 1086, 1167, 1174, 1210, 1258, 1268, 1323, 1368, 1387, 1407
assignment.py	94	7	93%	100, 115, 189, 208, 225–226, 271
blocks.py	140	7	95%	55, 92–96, 158, 166, 231
bytes.py	64	14	78%	13–45, 129
callsub.py	81	5	94%	32–33, 58, 108–109
flow_control.py	95	1	99%	56
iteration.py	198	5	97%	91–92, 107, 144, 206
itxn.py	323	37	89%	139–140, 142, 156, 164–169, 197, 204, 226–227, 560, 579–597, 666, 670, 684, 693–706
main.py	598	70	88%	127, 267, 271, 276–295, 300–319, 374, 398, 419, 437–438, 440, 448, 490, 577–578, 690, 722, 735–736, 784, 809, 846–848, 859, 924, 1002, 1015, 1056, 1121, 1124, 1132, 1135, 1143, 1174, 1200, 1209, 1333, 1350, 1393–1403
storage.py	83	2	98%	101, 154
src/puya/ir/destructure
coalesce_locals.py	101	19	81%	119, 128–129, 132–135, 138–147, 163–166
parcopy.py	84	2	98%	47, 83
src/puya/ir/optimize
collapse_blocks.py	92	5	95%	65–69
compiled_reference.py	79	5	94%	53, 87, 158–163
control_op_simplification.py	104	7	93%	47–48, 177, 253–260
inner_txn.py	36	1	97%	38
intrinsic_simplification.py	483	31	94%	76, 168–170, 175, 257, 269, 304, 315–316, 340–341, 365, 434, 621, 623, 638, 678, 701, 731, 737, 739, 741, 746, 748, 750, 752, 754, 806–807, 814
main.py	87	2	98%	118–119
src/puya/ir/validation
_base.py	30	1	97%	28
compile_reference_validator.py	20	2	90%	24, 30
min_avm_version_validator.py	15	4	73%	16–20
op_run_mode_validator.py	19	5	74%	19–29
src/puya/mir
aligned_writer.py	63	3	95%	21, 61, 80
builder.py	157	13	92%	71–73, 155, 267–268, 321, 324, 327, 330, 333, 336, 339
models.py	434	6	99%	98, 207, 251, 317, 334, 404
src/puya/mir/stack_allocation
f_stack.py	89	2	98%	23, 70
peephole.py	48	2	96%	47, 49
x_stack.py	205	3	99%	32, 336–340
src/puya/teal
models.py	369	2	99%	383, 444
src/puya/teal/optimize
constant_block.py	104	4	96%	63, 152, 189, 206
peephole.py	127	3	98%	162, 168, 251
repeated_rotations.py	51	1	98%	16
repeated_rotations_search.py	90	6	93%	35, 41–42, 58, 68–69
src/puya/ussemble
assemble.py	171	5	97%	134, 202, 219–220, 260
models.py	25	1	96%	16
op_spec_models.py	22	1	95%	20
src/puyapy
__main__.py	64	17	73%	177, 189–203, 207
client_gen.py	118	11	91%	65–66, 84–88, 92, 205, 212–213, 233
compile.py	150	22	85%	59–68, 82, 164–165, 176, 183–184, 201–211, 221–223, 228, 244
models.py	99	4	96%	65, 77–79
parse.py	180	13	93%	50–51, 87, 159–164, 168, 268, 272–273, 321, 333, 358
template.py	32	8	75%	10–11, 18–19, 27–28, 34, 37
utils.py	21	5	76%	16–17, 25–28
src/puyapy/awst_build
arc4_client.py	104	24	77%	46–50, 58, 70, 76, 80, 109, 115–116, 122, 125, 128, 134, 137, 145, 148, 151, 154, 157, 160, 163, 166, 169, 172
arc4_client_gen.py	132	8	94%	32, 91–92, 102, 104, 119–120, 187
arc4_utils.py	288	47	84%	42, 45–46, 48, 53–60, 78, 89–93, 109, 111, 114–115, 138, 181–183, 192, 197, 202–203, 229, 233, 245, 252, 254, 268–269, 272–276, 281–282, 288–291, 299, 307, 324, 336, 344, 446, 451, 470
base_mypy_visitor.py	127	39	69%	70–76, 94, 102–115, 129, 131, 133, 145, 150, 154, 157, 160, 166, 188, 191, 194, 201, 205, 208, 211, 215, 233, 237, 241, 245, 249, 253, 257, 261, 265, 269, 273, 277, 281
context.py	218	47	78%	55, 58, 68–69, 87–88, 128, 188, 193, 199–203, 207, 210, 219, 221, 224–226, 228, 235, 237, 248–249, 254–256, 259, 274, 286–287, 299, 313, 316–328
contract.py	319	33	90%	128, 179, 192–196, 236, 238, 242, 246, 254, 262, 264, 284, 339, 342, 354, 362, 365, 368, 371, 374, 377, 380, 383, 386, 389, 449–453, 502–506, 586–590, 661, 684
intrinsic_models.py	49	1	98%	55
main.py	36	1	97%	30
module.py	429	59	86%	118, 138, 144–148, 163–164, 171, 180–181, 189–193, 215, 244, 264–265, 276, 298–301, 311–313, 319, 336–339, 352, 386, 393, 415–416, 439–444, 498–499, 527, 538, 541, 547, 553, 563, 569, 572, 584, 587, 610, 630, 635, 639, 648–652, 744, 752, 754
pytypes.py	594	60	90%	87, 97–99, 104, 111, 116–118, 122–124, 151–152, 192, 210–216, 239, 259, 301, 339–341, 370, 436, 445, 464, 484, 506–507, 648–650, 664–665, 732–733, 837, 848–849, 898–899, 904, 957–958, 981–982, 1133–1134, 1158, 1186, 1222–1224, 1264, 1274–1275
subroutine.py	602	52	91%	136, 246, 252, 310–313, 319, 370, 375, 378–384, 475, 495, 650, 652–653, 671, 673, 683–684, 693–694, 698, 719, 785, 792, 812–813, 899, 925–926, 943, 959, 983, 991, 1002, 1028–1031, 1137–1138, 1158, 1168, 1170, 1179, 1197, 1205, 1219, 1222, 1225, 1228, 1231
utils.py	161	24	85%	30, 47–51, 69, 104–105, 107, 151–152, 203, 211, 216, 229–233, 238–241, 250, 254, 262
src/puyapy/awst_build/eb
_base.py	128	18	86%	52, 57–59, 64, 71, 76, 81–83, 142, 153, 183, 188, 193, 198, 209, 223–225
_bytes_backed.py	48	2	96%	30–31
_expect.py	122	21	83%	25, 36, 85–88, 100–103, 106, 158–159, 217–220, 230–233
_literals.py	144	29	80%	43, 72, 91, 120, 137, 151, 155, 159–165, 175–189, 194
_type_registry.py	40	4	90%	251–252, 264–265
utils.py	47	3	94%	28–30, 100
array.py	26	9	65%	23, 28–33, 43, 47
biguint.py	101	6	94%	56, 100, 139, 155–156, 158
binary_bool_op.py	105	3	97%	153, 161, 171
bool.py	55	9	84%	39–43, 59, 70, 83, 97
bytes.py	168	18	89%	103–104, 131–132, 137–138, 144–145, 148, 156, 199, 234, 266, 270, 287–288, 303–304
compiled.py	70	9	87%	86–90, 127–131, 154
conditional_literal.py	134	34	75%	98, 102, 162, 166–169, 178–180, 203–206, 215, 219, 223–226, 241–253, 262–263, 274–277
contracts.py	77	8	90%	55, 61, 63, 73, 99, 109, 111, 116
dict.py	27	5	81%	24, 32–34, 38
ensure_budget.py	31	1	97%	47
interface.py	90	3	97%	314–316, 320
intrinsics.py	97	6	94%	43, 62, 69, 82, 89, 160
log.py	43	4	91%	46–47, 52, 61
logicsig.py	15	1	93%	26
none.py	27	1	96%	38
string.py	144	13	91%	72, 116–117, 136, 141, 184, 191, 195, 207, 281–283, 303
struct.py	16	5	69%	14–16, 25, 29
subroutine.py	80	16	80%	47, 51–54, 69, 72–79, 94, 102–103, 105–108, 113
template_variables.py	37	2	95%	30, 58
tuple.py	339	13	96%	86, 134, 150, 240–241, 253, 346–347, 466, 535, 546–547, 610
uint64.py	108	6	94%	57, 118–119, 167–168, 200
uint64_enums.py	40	2	95%	41, 46
unsigned_builtins.py	155	22	86%	74, 81, 105, 129, 133, 137, 141, 149, 153, 157, 161, 165, 175, 179, 185, 196, 202, 208, 247, 279, 291, 303
src/puyapy/awst_build/eb/arc4
_base.py	92	3	97%	185–188, 199
_utils.py	141	7	95%	119, 127, 138, 178–181, 252, 256
abi_call.py	317	19	94%	118, 124, 145, 215, 228–229, 310, 322, 380, 403, 434, 453–454, 513, 549, 623, 708–709, 726
address.py	73	2	97%	57, 116
bool.py	58	3	95%	42, 87–88
dynamic_array.py	120	9	92%	56, 123–124, 145, 221, 241–242, 245–248
dynamic_bytes.py	68	3	96%	99–101
emit.py	34	1	97%	36
static_array.py	62	1	98%	44
string.py	98	7	93%	54–55, 103, 124, 129–132
struct.py	49	1	98%	49
tuple.py	93	16	83%	45–47, 70, 88–91, 94–95, 134–137, 142, 146–147, 157, 167
ufixed.py	70	2	97%	43, 102
src/puyapy/awst_build/eb/reference_types
account.py	79	2	97%	65, 175
application.py	45	1	98%	40
asset.py	65	1	98%	48
src/puyapy/awst_build/eb/storage
_common.py	69	3	96%	107, 120–121
_storage.py	108	20	81%	58, 66, 70, 74, 78, 82, 86, 90, 94, 104, 108, 112, 116, 122, 133, 139, 145, 157–159
_value_proxy.py	55	7	87%	38, 42, 50, 54, 91, 99, 103
box_map.py	147	1	99%	194
global_state.py	127	6	95%	104–105, 114–115, 164–165
local_state.py	137	11	92%	99–100, 104, 151, 155, 159, 169, 173, 197, 254, 278
src/puyapy/awst_build/eb/transaction
base.py	39	2	95%	23, 43
group.py	53	1	98%	48
inner.py	48	2	96%	91–92
inner_params.py	77	5	94%	64, 74, 78, 138, 140
itxn_args.py	60	1	98%	72
TOTAL	22788	1734	92%

Tests	Skipped	Failures	Errors	Time
835	2 💤	0 ❌	0 🔥	5m 48s ⏱️

[robdmoore]

Not all of the documentation on this page seems to have been replicated, e.g. this section (unless I'm missing something?)

[robdmoore]

I like the idea of moving more docs into doc strings - it's powerful for automation and maintenance and also improves intellisense.

One thing I would caution though is removing conceptual documentation completely isn't a good experience since, per the UX report we did, it's important to support unknown information tasks as well as known information tasks. Completely removing the ARC-4 page and requiring people to navigate to the specific parts of it in the A-Z index won't work for that. It may well be that the conceptual docs are kept in dev portal repo though.