PLAT-47 add docs for extending routes

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 Observes [Semantic Versioning](https://semver.org/spec/v2.0.0.html) standard and [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) convention.
 
+## [0.8.7] - 2023-08-08
+
+### Added
+
+- Migrate documentation to MkDocs [#164](https://github.com/datajoint/pharus/pull/164)
+- Add section in docs for extending pharus [#165](https://github.com/datajoint/pharus/pull/165)
+
 ## [0.8.6] - 2023-05-2
 
 ### Added

docs/src/dev.md

@@ -67,6 +67,67 @@
   flake8 ${PKG_DIR} --count --max-complexity=20 --max-line-length=94 --statistics --exclude=*dynamic_api.py --ignore=W503
   ```
 
+## Extending Pharus Routes
+
+Pharus' routes can be extended through the spec sheet.
+
+### Guide
+
+1. Define the YAML spec sheet. Under `SciViz.component_interface.override`, in a string block:
+
+   1. Import the `type_map` and base components from the pharus `component.interface` module, as well as any other libraries needed.
+   2. Define a class that extends one of the base components. If extending `Component`, the rest verb must be manually set.
+
+      - Within the class, define a `dj_query_route` method with the functionality of your custom route. Ensure it returns a dictionary.
+
+   3. Extend the `type_map` with a mapping of the name of you want to give to the component to the new class.
+
+      - The new name can now be used as a type in the `components` section of the spec.
+
+2. Inject the spec into pharus
+   1. Mount the spec sheet into the container.
+   2. Set the `PHARUS_SPEC_PATH` environment variable.
+
+### Example
+
+```yaml
+SciViz:
+  auth:
+    mode: database | oidc | none
+  component_interface:
+    override: |
+      # import `type_map`, the base components to be extended, and any other libraries necessary
+      from pharus.component_interface import type_map, Component
+
+      # define custom class extending a base component
+      class ExampleComponent(Component):
+          # set necessary REST verb(s) if extending generic `Component`
+          rest_verb=["GET"]
+
+          # define `dj_query_route` method that returns some dictionary
+          def dj_query_route(self):
+              # some code
+              return {"example": "example response"}
+
+      # extend the `type_map` with a custom type prefixed with the component type you are extending mapped to the custom component
+      type_map = {
+          **type_map, 'external:ExampleType': ExampleComponent
+      }
+  pages:
+    page:
+      route: /page
+      hidden: true
+      grids:
+        grid:
+          type: fixed
+          components:
+            example_component:
+              route: /example_route
+              type: external:ExampleType
+```
+
+For more information about the spec sheet, visit the [SciViz docs](https://datajoint.com/docs/core/sci-viz/2.3/concepts/spec_sheet/).
+
 ## Creating MkDocs Documentation
 
 Run the following command with the appropriate parameters:

pharus/server.py

@@ -127,7 +127,7 @@ def api_version() -> str:
     Content-Type: application/json
 
     {
-        "version": "0.8.6"
+        "version": "0.8.7"
     }
     ```
 

pharus/version.py

@@ -1,2 +1,2 @@
 """Package metadata."""
-__version__ = "0.8.6"
+__version__ = "0.8.7"