Add model field metadata; revise tour model

Address comments in code review
Model is revised due to change in Tour model spec:
- Id field is no longer part of the yaml file spec;
- However, an id is generated and added to the tour data returned as a
list
- As a result, in a list, a tour item must have an id, whereas in tour
details, a tour item must not have an id.
I've factored out "core tour" data into its own model to solve this.

lib/galaxy/tours/__init__.py

@@ -8,7 +8,10 @@
 from pydantic import parse_obj_as
 
 from galaxy import util
-from galaxy.tours.schema import TourList
+from galaxy.tours.schema import (
+    TourDetails,
+    TourList,
+)
 
 
 log = logging.getLogger(__name__)
@@ -45,7 +48,7 @@ def tours_by_id_with_description(self) -> TourList:
             tours.append(tourdata)
         return parse_obj_as(TourList, tours)
 
-    def load_tour(self, tour_id):
+    def load_tour(self, tour_id) -> TourDetails:
         for tour_dir in self.tour_directories:
             tour_path = os.path.join(tour_dir, tour_id + ".yaml")
             if not os.path.exists(tour_path):
@@ -67,7 +70,7 @@ def reload_tour(self, path):
         if self._is_yaml(filename):
             self._load_tour_from_path(path)
 
-    def tour_contents(self, tour_id):
+    def tour_contents(self, tour_id) -> TourDetails:
         # Extra format translation could happen here (like the previous intro_to_tour)
         # For now just return the loaded contents.
         return self.tours.get(tour_id, None)

lib/galaxy/tours/schema.py

@@ -3,31 +3,80 @@
     Optional,
 )
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 
-class Tour(BaseModel):
-    id: str
-    name: str
-    description: str
-    tags: List[str]
+class TourCore(BaseModel):
+    name: str = Field(
+        title='Name',
+        description='Name of tour'
+    )
+    description: str = Field(
+        title='Description',
+        description='Tour description'
+    )
+    tags: List[str] = Field(
+        title='Tags',
+        description='Topic topic tags'
+    )
+
+
+class Tour(TourCore):
+    id: str = Field(
+        title='Identifier',
+        description='Tour identifier'
+    )
 
 
 class TourList(BaseModel):
-    __root__: List[Tour] = []
+    __root__: List[Tour] = Field(
+        title='List of tours',
+        default=[]
+    )
 
 
 class TourStep(BaseModel):
-    title: Optional[str] = None
-    content: Optional[str] = None
-    element: Optional[str] = None
-    placement: Optional[str] = None
-    preclick: Optional[list] = None
-    postclick: Optional[list] = None
-    textinsert: Optional[str] = None
-    backdrop: Optional[bool] = None
-
-
-class TourDetails(Tour):
-    title_default: Optional[str] = None
-    steps: List[TourStep]
+    title: Optional[str] = Field(
+        title='Title',
+        description='Title displayed in the header of the step container'
+    )
+    content: Optional[str] = Field(
+        title='Content',
+        description='Text shown to the user'
+    )
+    element: Optional[str] = Field(
+        title='Element',
+        description='JQuery selector for the element to be described/clicked'
+    )
+    placement: Optional[str] = Field(
+        title='Placement',
+        description='Placement of the text box relative to the selected element'
+    )
+    preclick: Optional[list] = Field(
+        title='Pre-click',
+        description='Elements that receive a click() event before the step is shown'
+    )
+    postclick: Optional[list] = Field(
+        title='Post-click',
+        description='Elements that receive a click() event after the step is shown'
+    )
+    textinsert: Optional[str] = Field(
+        title='Text-insert',
+        description='Text to insert if element is a text box (e.g. tool search or upload)'
+    )
+    backdrop: Optional[bool] = Field(
+        title='Backdrop',
+        description=('Show a dark backdrop behind the popover and its element,'
+            'highlighting the current step')
+    )
+
+
+class TourDetails(TourCore):
+    title_default: Optional[str] = Field(
+        title='Default title',
+        description='Default title for each step'
+    )
+    steps: List[TourStep] = Field(
+        title='Steps',
+        description='Tour steps'
+    )