409 convert docstrings to use mkdocstring google style (#416)

* Start API documentation section

* Re-organize home

* Generate full code reference

* Fixed naming of bindings, add references to documentation in add a manipulator

* Renamed utils, added code org

* Convert to google style

* Separate install section

docs/development/adding_a_manipulator.md

@@ -1,3 +1,5 @@
+# Adding a Manipulator
+
 By the end of this section, you will be able to add a manipulator platform to Ephys Link and control it using the server
 API. This is a software development guide and assumes you have experience with Python. It is encouraged to
 read [how the system works first](../home/how_it_works.md) before proceeding.
@@ -11,17 +13,21 @@ read [how the system works first](../home/how_it_works.md) before proceeding.
 ## Create a Manipulator Binding
 
 Manipulators are added to Ephys Link through bindings. A binding is a Python class that extends the abstract base class
-`BaseBinding` and defines the functions Ephys Link expects from a platform.
+[`BaseBinding`][ephys_link.utils.base_binding] and defines the functions Ephys Link expects from a platform.
 
 Create a new Python module in `src/ephys_link/bindings` for your manipulator. Make a class that extends
-`BaseBinding`. Most IDEs will automatically import the necessary classes and tell you the methods you need to
-implement. These functions have signature documentation describing what they should do.
+[`BaseBinding`][ephys_link.utils.base_binding]. Most IDEs will automatically import the necessary classes and tell you
+the methods you need to implement. See the reference for [`BaseBinding`][ephys_link.utils.base_binding] for detailed
+descriptions of the expected behavior.
 
 As described in the [system overview](../home/how_it_works.md), Ephys Link converts all manipulator movement into a
 common "unified space" which is
 the [left-hand cartesian coordinate system](https://www.scratchapixel.com/lessons/mathematics-physics-for-computer-graphics/geometry/coordinate-systems.html).
-The two functions `platform_space_to_unified_space` and `unified_space_to_platform_space` are used to convert between
-your manipulator's coordinate system and the unified space.
+The two functions [
+`platform_space_to_unified_space`](../../reference/ephys_link/utils/base_binding/#ephys_link.utils.base_binding.BaseBinding.platform_space_to_unified_space)
+and [
+`unified_space_to_platform_space`](../../reference/ephys_link/utils/base_binding/#ephys_link.utils.base_binding.BaseBinding.unified_space_to_platform_space)
+are used to convert between your manipulator's coordinate system and the unified space.
 
 !!! tip
 

docs/development/code_organization.md

@@ -1,3 +1,27 @@
-!!! warning "Under Construction"
+# Code Organization
 
-    This documentation page is still under construction. Please come back later for more information!
+This section gives an overview of Ephys Link's internal architecture. It is intended for
+maintainers of Ephys Link.
+
+## File Structure
+
+Ephys Link starts from the `__main__.py` file. It imports each component of the application and calls the launch
+sequence.
+
+### Where to find things
+
+- `back_end`: the Socket.IO server and the manipulator API.
+- `front_end`: configuration GUI and CLI definition.
+- `bindings`: manipulator binding implementations.
+- `utils`: common utilities and helper functions (including
+  [the base binding abstract base class][ephys_link.utils.base_binding]).
+
+## Control Flow
+
+As described in ["How It Works"](../home/how_it_works.md), Ephys Link is primarily a server that responds to events. The
+server exposes the events and pass them to the chosen manipulator binding. Everything is asynchronous and uses callbacks
+to return responses to the clients when ready.
+
+[`PlatformHandler`][ephys_link.back_end.platform_handler] is responsible for converting between the server API and the
+manipulator binding API. Because of this module, you don't have to worry about the details of the server API when
+writing a manipulator binding.

docs/development/index.md

@@ -7,7 +7,8 @@ This section describes:
 
 - [The Socket.IO server's API](socketio_api.md) and how to communicate with Ephys Link from a client application
 - How to [add a new manipulator](adding_a_manipulator.md) to Ephys Link
-- General [code organization](code_organization.md) and development practices for Ephys Link
+- General [code organization](code_organization.md) for Ephys Link
+- Auto generated [source code reference](../reference/SUMMARY.md) intended for developers who are maintaining Ephys Link
 
 ## Installing for Development
 

docs/development/socketio_api.md

@@ -1,3 +1,5 @@
+# Socket.IO API
+
 This section documents the Socket.IO API. The document is intended for developers building client applications that
 communicate with the server. If you are looking for information on how to set up and run the server, see the
 [installation guide](../home/installation.md)!

docs/home/contact.md

@@ -1,3 +1,5 @@
+# Contact
+
 Kenneth J. Yang is the primary developer and maintainer of Ephys Link. You can find his contact information on the
 VBL [about page](https://virtualbrainlab.org/about/overview.html) along with Daniel Birman's (the co-developer of Ephys Link).
 

docs/home/how_it_works.md

@@ -1,3 +1,5 @@
+# How It Works
+
 This section provides an overview of how Ephys Link works. It is intended for users who want to understand the
 software's architecture and how it interacts with other systems.
 

docs/home/installation.md

@@ -1,3 +1,5 @@
+# Installation
+
 ## Prerequisites
 
 1. An **x86 Windows PC is required** to run the server.
@@ -20,6 +22,8 @@ on [connecting from Pinpoint](../usage/connecting_to_pinpoint.md).
 
 Download the latest executable from the [releases page](https://github.com/VirtualBrainLab/ephys-link/releases/latest).
 
+Then see the [usage documentation](../usage/index.md) for how to run the server.
+
 ## Install as a Python package
 
 ```bash
@@ -32,6 +36,8 @@ or with [pipx](https://pipx.pypa.io/stable/) (recommended)
 pipx install ephys-link
 ```
 
+Then see the [usage documentation](../usage/index.md) for how to run the server.
+
 ## Install for Development
 
 See [development documentation](../development/index.md#installing-for-development) for more information.

docs/home/supported_manipulators.md

@@ -1,3 +1,5 @@
+# Supported Manipulators
+
 This is a current list of planned and supported manipulators in Ephys Link. If you use a manipulator that is not listed
 here, we suggest reaching out to your manipulator's manufacturer to request support for Ephys Link. Direct them to
 contact [Kenneth Yang and Daniel Birman](https://virtualbrainlab.org/about/overview.html)!

docs/stylesheets/mkdocstrings.css

@@ -0,0 +1,42 @@
+/* Fancier color for operators such as * and |. */
+.doc-signature .o {
+    color: var(--md-code-hl-special-color);
+}
+
+/* Fancier color for constants such as None, True, and False. */
+.doc-signature .kc {
+    color: var(--md-code-hl-constant-color);
+}
+
+/* Fancier color for built-in types (only useful when cross-references are used). */
+.doc-signature .n > a[href^="https://docs.python.org/"][href*="/functions.html#"],
+.doc-signature .n > a[href^="https://docs.python.org/"][href*="/stdtypes.html#"] {
+    color: var(--md-code-hl-constant-color);
+}
+/* Indentation. */
+div.doc-contents:not(.first) {
+    padding-left: 25px;
+    border-left: .05rem solid var(--md-typeset-table-color);
+}
+
+/* Mark external links as such. */
+a.external::after,
+a.autorefs-external::after {
+    /* https://primer.style/octicons/arrow-up-right-24 */
+    mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+    -webkit-mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+    content: ' ';
+
+    display: inline-block;
+    vertical-align: middle;
+    position: relative;
+
+    height: 1em;
+    width: 1em;
+    background-color: currentColor;
+}
+
+a.external:hover::after,
+a.autorefs-external:hover::after {
+    background-color: var(--md-accent-fg-color);
+}

docs/usage/connecting_to_pinpoint.md

@@ -1,3 +1,5 @@
+# Connecting to Pinpoint
+
 [Pinpoint](https://github.com/VirtualBrainLab/Pinpoint) is a tool for planning electrophysiology recordings and other
 _in vivo_ insertions, as well as tracking the position of probes in real-time inside the brain.
 

docs/usage/experiment_automation.md

@@ -1,3 +1,5 @@
+# Experiment Automation
+
 Pinpoint and Ephys Link can work together to automate manual procedures in electrophysiology experiments. Follow the
 [instructions on Pinpoint's documentation](https://virtualbrainlab.org//pinpoint/tutorials/tutorial_ephys_copilot.html)
 to use automation in your next experiment!

docs/usage/index.md

@@ -1,4 +1,4 @@
-# Using Ephys Link
+# Starting Ephys Link
 
 Ephys Link is a server that runs in the background.
 

mkdocs.yml

@@ -43,10 +43,13 @@ theme:
     - navigation.tabs
     - navigation.tabs.sticky
     - navigation.sections
-    - navigation.indexes
+    - navigation.expand
+    - navigation.top
+    - navigation.footer
     - toc.follow
 extra_css:
   - stylesheets/extra.css
+  - stylesheets/mkdocstrings.css
 markdown_extensions:
   - admonition
   - attr_list
@@ -69,25 +72,38 @@ markdown_extensions:
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
 plugins:
   - search
+  - gen-files:
+      scripts:
+        - scripts/gen_ref_pages.py
+  - literate-nav:
+      nav_file: SUMMARY.md
+  - section-index
   - mkdocstrings:
       handlers:
         python:
           paths: [ src ]
           options:
-            docstring_style: sphinx
+            docstring_style: google
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+          import:
+            - https://docs.python.org/3/objects.inv
+            - https://virtualbrainlab.github.io/vbl-aquarium/objects.inv
 nav:
   - Home:
-      - index.md
-      - Installation: home/installation.md
-      - "How it Works": home/how_it_works.md
-      - "Supported Manipulators": home/supported_manipulators.md
-      - Contact: home/contact.md
+      - About: index.md
+      - Getting Started:
+          - Installation: home/installation.md
+          - home/how_it_works.md
+          - home/supported_manipulators.md
+      - home/contact.md
   - Usage:
       - usage/index.md
-      - "Connecting to Pinpoint": usage/connecting_to_pinpoint.md
-      - "Experiment Automation": usage/experiment_automation.md
+      - usage/connecting_to_pinpoint.md
+      - usage/experiment_automation.md
   - Development:
       - development/index.md
-      - "Socket.IO API": development/socketio_api.md
-      - "Adding a Manipulator": development/adding_a_manipulator.md
-      - "Code Organization": development/code_organization.md
+      - development/socketio_api.md
+      - development/adding_a_manipulator.md
+      - development/code_organization.md
+      - Source Code Reference: reference/

pyproject.toml

@@ -38,7 +38,7 @@ dependencies = [
     "requests==2.32.3",
     "sensapex==1.400.3",
     "rich==13.9.4",
-    "vbl-aquarium==0.0.23"
+    "vbl-aquarium==1.0.0b1"
 ]
 
 [project.urls]
@@ -71,7 +71,10 @@ python = "3.13.1"
 skip-install = true
 dependencies = [
     "mkdocs-material==9.5.49",
-    "mkdocstrings-python==1.12.2",
+    "mkdocstrings-python==1.13.0",
+    "mkdocs-gen-files==0.5.0",
+    "mkdocs-literate-nav==0.6.1",
+    "mkdocs-section-index==0.3.9"
 ]
 [tool.hatch.envs.docs.scripts]
 serve = "mkdocs serve"

scripts/gen_ref_pages.py

@@ -0,0 +1,35 @@
+"""Generate the code reference pages."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+root = Path(__file__).parent.parent
+src = root / "src"
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src).with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1] == "__main__":
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        identifier = ".".join(parts)
+        print("::: " + identifier, file=fd)
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

scripts/move_tester.py

@@ -4,7 +4,7 @@
 from vbl_aquarium.models.unity import Vector4
 
 from ephys_link.back_end.platform_handler import PlatformHandler
-from ephys_link.util.console import Console
+from ephys_link.utils.console import Console
 
 c = Console(enable_debug=True)
 p = PlatformHandler(EphysLinkOptions(type="pathfinder-mpm"), c)

src/ephys_link/__about__.py

@@ -1 +1 @@
-__version__ = "2.0.0b7"
+__version__ = "2.0.0b8"

src/ephys_link/__main__.py

@@ -2,7 +2,10 @@
 
 Responsible for gathering launch options, instantiating the appropriate interface, and starting the application.
 
-Usage: call main() to start.
+Usage:
+    ```python
+    main()
+    ```
 """
 
 from sys import argv
@@ -11,7 +14,7 @@
 from ephys_link.back_end.server import Server
 from ephys_link.front_end.cli import CLI
 from ephys_link.front_end.gui import GUI
-from ephys_link.util.console import Console
+from ephys_link.utils.console import Console
 
 
 def main() -> None: