1627 facilities in nav bar menu

docs/common/customsettings.rst

@@ -181,6 +181,9 @@ A list of observation facility classes to make available to your TOM. If
 you have written or downloaded a custom observation facility you would
 add the class to this list to make your TOM load it.
 
+INSTALLED_APPS that implement the ``observation_facilities()`` AppConfig integration
+point do not need to be listed here.
+
 `TOM_LATEX_PROCESSORS <#tom-latex-processors>`__
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/observing/observation_module.rst

@@ -105,6 +105,28 @@ like this:
 This means our new observation facility module has been successfully
 loaded.
 
+Adding a facility from an app
+-----------------------------
+
+A facility implemented as a Django reusable app can advertise itself
+to a TOM without the editing ``settings.py``, which simplifies it's installation.
+To do this, implement the ``observation_facilities()`` integration point
+on the app's ``AppConfig`` subclass:
+
+.. code:: python
+
+   class MyAppConfig(AppConfig):
+       name = 'myapp'
+
+       def observation_facilities(self):
+           return [{'class': f'{self.name}.myfacility.MyObservationFacility'}]
+
+Facilities from both ``settings.TOM_FACILITY_CLASSES`` and the apps implementing
+the integration point are merged by ``tom_observations.facility.get_service_classes()``.
+So, if your facility implements the ``observation_facilities()`` integration point,
+adding the app to ``INSTALLED_APPS`` is all that is required for installation.
+See ``tom_demoapp`` for a worked example.
+
 BaseRoboticObservationFacility and BaseRoboticObservationForm
 -------------------------------------------------------------
 
@@ -126,6 +148,47 @@ use. The ``BaseRoboticObservationForm`` class, just like the previous
 super class, contains logic and layout that all observation facility
 form classes should contain.
 
+Linking to a facility detail page
+---------------------------------
+
+A facility may set ``detail_url_name`` to the namespaced Django URL name of a page
+describing the facility. Facilities that set it appear in the navbar **Facilities**
+dropdown, linked to that page:
+
+.. code:: python
+
+   class MyObservationFacility(BaseRoboticObservationFacility):
+       name = 'MyFacility'
+       detail_url_name = 'myapp:facility-detail'
+
+``detail_url_name`` is optional and is omitted from the minimal example above. A facility
+that leaves it unset is still fully registered -- it has an observe button and observation
+forms -- but gets no menu item. If no facility sets it, the dropdown is not displayed.
+See ``tom_demoapp`` for a worked example, including composing the namespace from the
+AppConfig's ``url_namespace`` attribute.
+
+For ``detail_url_name`` to resolve, the app's URLs must be mounted in the TOM under that
+namespace. A reusable app mounts its own ``urls.py`` through the ``include_url_paths()``
+AppConfig integration point -- ``tom_common`` collects these paths from every installed
+app, so no TOM ``urls.py`` edits are required:
+
+.. code:: python
+
+   class MyAppConfig(AppConfig):
+       name = 'myapp'
+       url_prefix = 'myapp'     # URL path prefix for this app's pages: HOST/myapp/...
+       url_namespace = 'myapp'  # the namespace half of detail_url_name
+
+       def include_url_paths(self):
+           return [
+               path(f'{self.url_prefix}/', include(f'{self.name}.urls', namespace=self.url_namespace)),
+           ]
+
+(``url_prefix`` and ``url_namespace`` are TOM plugin conventions, not Django AppConfig
+attributes.) The included ``urls.py`` must set ``app_name`` -- Django requires it when
+``include()`` is called with ``namespace=`` -- and must contain a ``path()`` whose
+``name=`` is the second half of ``detail_url_name``.
+
 Implementing observation submission
 -----------------------------------
 

tom_dataservices/dataservices.py

@@ -24,7 +24,7 @@ def get_data_service_classes():
     """
     Imports the Dataservice class from relevant apps and generates a list of data service names.
 
-    Each dataservice class should be contained in a list of dictionaries in an app's apps.py `dataservices` method.
+    Each dataservice class should be contained in a list of dictionaries in an app's apps.py `data_services` method.
     Each dataservice dictionary should contain a 'class' key with the dot separated path to the dataservice class
     (typically an extension of DataService).
 
@@ -84,8 +84,9 @@ class QueryServiceError(Exception):
 
 
 class DataService(ABC):
-    """
-    Base class for all Data Services. Data Services are classes that are responsible for querying external services
+    """Base class for all Data Services.
+
+    Data Services are classes that are responsible for querying external services
     and returning data.
     """
     # Recognizable name for the DataService (Gaia, TNS, etc)
@@ -123,11 +124,11 @@ def query_service(self, query_parameters, **kwargs):
         """Takes in the serialized data from the query form and actually submits the query to the service"""
 
     def pre_query_validation(self, query_parameters):
-        """Same thing as query_service, but a dry run"""
+        """Same thing as query_service, but a dry run."""
         raise NotImplementedError(f'pre_query_validation method has not been implemented for {self.name}')
 
     def build_query_parameters(self, parameters, **kwargs):
-        """Builds the query parameters from the form data"""
+        """Builds the query parameters from the form data."""
         raise NotImplementedError(f'build_query_parameters method has not been implemented for {self.name}')
 
     # Include this method if you wish for the TOM to be able to query data for an individual Target.
@@ -200,7 +201,7 @@ def get_credentials(cls, **kwargs):
 
     @classmethod
     def urls(cls, **kwargs) -> dict:
-        """Dictionary of URLS for the DataService"""
+        """Dictionary of URLS for the DataService."""
         return {'base_url': cls.base_url, 'info_url': cls.info_url}
 
     @classmethod
@@ -387,6 +388,7 @@ def to_target(self, target_result=None, **kwargs):
 
     def create_target_from_query(self, target_result, **kwargs):
         """Create a new target from a single instance of the target results.
+
         :param target_result: dictionary describing target details based on query result
         :returns: target object
         :rtype: `Target`
@@ -420,7 +422,8 @@ def to_aliases(self, target, alias_results: List, **kwargs) -> List:
         return new_aliases
 
     def create_aliases_from_query(self, alias_results: List, **kwargs) -> List:
-        """Create a new target name from the query results
+        """Create a new target name from the query results.
+
         This method should be over ridden with a method that creates a list of TargetName objects:
         `TargetName(name=alias)` that will be saved as part of the `Target.save(extras=extras, names=aliases)` call.
         :param query_result: list of dictionaries describing target details based on query result

tom_observations/apps.py

@@ -3,3 +3,14 @@
 
 class TomObservationsConfig(AppConfig):
     name = 'tom_observations'
+
+    def nav_items(self):
+        """Integration point for adding items to the navbar.
+
+        This method should return a list of partial templates to be included in the navbar.
+
+        Here, the "Facilities" dropdown menu, listing the facilities contributed by installed
+        apps via the observation_facilities() integration point (see ``tom_demoapp`` for example).
+        """
+        return [{'partial': 'tom_observations/partials/navbar_facilities_list.html',
+                 'context': 'tom_observations.templatetags.observation_extras.observation_facilities_list'}]