Document automatic indexing

[gpeairs]

This isn't yet documented. index_layer! has no docstring and isn't exported, and the SolidModelTarget docstring says "- indexed_layers: A list of layer Symbols to be turned into separate PhysicalGroups with "_\$i" appended for each index i. These layers will be automatically indexed if not already present in a Schematic's index_dict." It would be best for the docs to tie it to examples/applications (it's already used in the single transmon example), also explaining how to use it with index_dict. We should explain in more detail somewhere (not necessarily the example) specifically how index_layer! and automatic indexing works. Some of this detail and/or index_layer! itself may be "internals" and subject to breaking changes, although we should still document them to make that explicit and help with development/debugging. For temporary reference, here's my brief explanation as of v1.3:

For each layer in a SolidModelTarget's indexed_layers, we look through the schematic's components (in the order they were added) for entities in those layers, set the index of those entities' metadata to zero, and make a copy of each entity outside the component with an incremented index starting at 1. This lets us associate that port index with its component in the schematic's index_dict entry for that layer. (It's a copy outside the component so that there's no risk that its coordinate system gets referenced elsewhere.) So for everything that's automatically indexed, we end up with a copy with index 0. Index 0 gets assigned to the physical group without any suffix ("port" rather than "port_0").

Elements of the top-level coordinate system schematic.coordinate_system in indexed layers just have their index incremented.

Any entities in indexed layers outside components or the top-level coordinate system are ignored, so if you manually add ports inside references in the top-level coordinate system, those will have whatever index they started with (default 1). They will still have any suffix appropriate for that index.

Paths should not have metadata whose layer is in indexed_layers. If you're using a path to position an indexed entity, use an entity in an attach!-ed reference.