Organize divisions pkg, add missing relationships, tidy and add docs

This commit organizes the divisions Pydantic package to align with the
other packages that have been done so far: addresses, base, buildings,
and places. After this commit there remains only: transportation and
core (the latter will soon be renamed common).

Organization work done:

1. Common code into `_common.py`.
2. Each feature type gets its own main module, e.g., `division.py`.
3. Types used exclusively by a feature type into that feature type's main
   module, regardless of whether the type is an enum, model, NewType, etc.
4. Eliminate sub-directories.
5. Curate `__all__` in `__init__.py`.

Missing relationships added:

1. `CapitalOfItem`
2. `HierarchyItem`
3. `parent_division_id` in `Division`
4. `capital_division_ids` in `Division`

Getting this to work required extending the list of relationships in the
system package's `ref.py`. (On this, note, that Tristan will likely
shrink it back to managable size when he rationalizes the
relationships.) It also required solving an issue with Python forward
references being in the Pydantic field annotations for `CapitalOfItem`
and `HierarchyItem`, which was breaking codegen. I fixed this issue by
using `.model_rebuild()` on both models, see `divisions.py`.

Docs tidied and updated:

1. Eliminated all `make docformat` errors pertaining to divisions.
2. Converted several enums to `DocumentedEnum` so they can have a richer
   presence in the schema reference.
3. Added missing docstrings and `Field(description="...")` annotations.
4. Edited and refined some of the documentation wording where it wasn't
   fully up to standard.
5. Wrapped long doc/desc lines using `textwrap.dedent("...").strip()` so
   the docs are easier to read and edit in a code editor.

Signed-off-by: schapper <schapper@amazon.com>

Author: vcschapp

packages/overture-schema-base-theme/src/overture/schema/base/__init__.py

@@ -36,7 +36,7 @@
     "LandSubtype",
     "LandUse",
     "LandUseClass",
-    "LandUseSubtype"
+    "LandUseSubtype",
     "SourceTags",
     "SurfaceMaterial",
     "Water",

packages/overture-schema-base-theme/tests/bathymetry_baseline_schema.json

@@ -214,7 +214,7 @@
       "properties": {
         "cartography": {
           "$ref": "#/$defs/CartographicHints",
-          "title": "cartography"
+          "description": "Cartographic hints useful when including the feature in maps"
         },
         "depth": {
           "description": "Depth below surface level of the feature in meters.",

packages/overture-schema-base-theme/tests/infrastructure_baseline_schema.json

@@ -630,7 +630,8 @@
           "type": "integer"
         },
         "names": {
-          "$ref": "#/$defs/Names"
+          "$ref": "#/$defs/Names",
+          "description": "All known names by which the feature is called"
         },
         "source_tags": {
           "additionalProperties": true,

packages/overture-schema-base-theme/tests/land_baseline_schema.json

@@ -505,7 +505,8 @@
           "type": "integer"
         },
         "names": {
-          "$ref": "#/$defs/Names"
+          "$ref": "#/$defs/Names",
+          "description": "All known names by which the feature is called"
         },
         "source_tags": {
           "additionalProperties": true,

packages/overture-schema-base-theme/tests/land_cover_baseline_schema.json

@@ -231,7 +231,7 @@
       "properties": {
         "cartography": {
           "$ref": "#/$defs/CartographicHints",
-          "title": "cartography"
+          "description": "Cartographic hints useful when including the feature in maps"
         },
         "sources": {
           "description": "Information about the source data used to assemble the feature.",

packages/overture-schema-base-theme/tests/land_use_baseline_schema.json

@@ -582,7 +582,8 @@
           "type": "integer"
         },
         "names": {
-          "$ref": "#/$defs/Names"
+          "$ref": "#/$defs/Names",
+          "description": "All known names by which the feature is called"
         },
         "source_tags": {
           "additionalProperties": true,

packages/overture-schema-base-theme/tests/water_baseline_schema.json

@@ -469,7 +469,8 @@
           "type": "integer"
         },
         "names": {
-          "$ref": "#/$defs/Names"
+          "$ref": "#/$defs/Names",
+          "description": "All known names by which the feature is called"
         },
         "source_tags": {
           "additionalProperties": true,

packages/overture-schema-buildings-theme/tests/building_baseline_schema.json

@@ -560,7 +560,8 @@
           "type": "number"
         },
         "names": {
-          "$ref": "#/$defs/Names"
+          "$ref": "#/$defs/Names",
+          "description": "All known names by which the feature is called"
         },
         "num_floors": {
           "description": "Number of above-ground floors of the building or part.",

packages/overture-schema-buildings-theme/tests/building_part_baseline_schema.json

@@ -444,7 +444,8 @@
           "type": "number"
         },
         "names": {
-          "$ref": "#/$defs/Names"
+          "$ref": "#/$defs/Names",
+          "description": "All known names by which the feature is called"
         },
         "num_floors": {
           "description": "Number of above-ground floors of the building or part.",

packages/overture-schema-codegen/tests/test_type_placement.py

@@ -132,17 +132,6 @@ def test_supplementary_types_nested_under_types(self) -> None:
             "buildings/types/building_class.md"
         )
 
-    def test_submodule_supplementary_types_nested_under_types(self) -> None:
-        """Supplementary types in a feature subdirectory go under types/."""
-        specs = flat_specs_from_discovery("divisions")
-        registry, _ = _build_registry(specs)
-
-        # AreaClass is from overture.schema.divisions.division_area.enums,
-        # a subdirectory of the divisions feature directory.
-        assert lookup_by_name(registry, "AreaClass") == PurePosixPath(
-            "divisions/types/division_area/area_class.md"
-        )
-
     def test_shared_types_not_nested(self) -> None:
         """Core/system supplementary types stay at their module-mirrored path."""
         specs = flat_specs_from_discovery("buildings")