Doc update 20250405 (#71)

KaminaDuck · web-flow · commit 4c1524b738bc · 2025-04-12T14:12:36.000-05:00
* added folder for doc builds

Signed-off-by: charlie.rogers &lt;charlie.rogers@fearnworks.com&gt;

* formatting for index page

Signed-off-by: charlie.rogers &lt;charlie.rogers@fearnworks.com&gt;

* removed script configuration

Signed-off-by: charlie.rogers &lt;charlie.rogers@fearnworks.com&gt;

* updated port on localhost

Signed-off-by: charlie.rogers &lt;charlie.rogers@fearnworks.com&gt;

* updated Getting Started

Signed-off-by: charlie.rogers &lt;charlie.rogers@fearnworks.com&gt;

* added pic of home screen

Signed-off-by: charlie.rogers &lt;charlie.rogers@fearnworks.com&gt;

* added second pic for showing instructions

Signed-off-by: charlie.rogers &lt;charlie.rogers@fearnworks.com&gt;

* updated with new directions

Signed-off-by: charlie.rogers &lt;charlie.rogers@fearnworks.com&gt;

* removed references to pipeline and workspaces from getting started

Signed-off-by: charlie.rogers &lt;charlie.rogers@fearnworks.com&gt;

* fixed pathing on action drawers image

Signed-off-by: charlie.rogers &lt;charlie.rogers@fearnworks.com&gt;

* updated picture with new interface

Signed-off-by: charlie.rogers &lt;charlie.rogers@fearnworks.com&gt;

* adjusted lists for action drawers

Signed-off-by: charlie.rogers &lt;charlie.rogers@fearnworks.com&gt;

* getting more navigation configured

Signed-off-by: Charlie Rogers &lt;charlie.rogers@fearnworks.com&gt;

* fixed spacing on the graphics

Signed-off-by: Charlie Rogers &lt;charlie.rogers@fearnworks.com&gt;

---------

Signed-off-by: charlie.rogers &lt;charlie.rogers@fearnworks.com&gt;
Signed-off-by: Charlie Rogers &lt;charlie.rogers@fearnworks.com&gt;
diff --git a/.gitignore b/.gitignore
@@ -23,4 +23,7 @@ test_logs.jsonl
 docker-compose.override.yml
 node_modules/
 graphcap_pg.session.sql
-media_server_v2/
+media_server_v2/
+
+# Doc build files
+doc/_build/*
diff --git a/doc/concepts/perspectives.rst b/doc/concepts/perspectives.rst
@@ -1,3 +1,5 @@
+.. _perspectives:
+
 ===========================
 Perspectives in graphcap
 ===========================
diff --git a/doc/dev/architecture.rst b/doc/dev/architecture.rst
@@ -1,3 +1,5 @@
+.. _architecture:
+
 =================================
 graphcap Architecture Overview
 =================================
diff --git a/doc/dev/caption_pipeline.rst b/doc/dev/caption_pipeline.rst
diff --git a/doc/dev/servers/data_service.rst b/doc/dev/servers/data_service.rst
@@ -1,3 +1,5 @@
+.. _data_service:
+
 =================================
 graphcap Data Service Architecture
 =================================
@@ -38,8 +40,8 @@ Architecture Components
 .. code-block:: text
 
    ┌──────────────────────────────────────────────────────┐
-   │                    Data Service                       │
-   │                                                       │
+   │                    Data Service                      │
+   │                                                      │
    │  ┌─────────────┐      ┌──────────────┐     ┌────────┐│
    │  │             │      │              │     │        ││
    │  │  Hono API   ├──────┤  Repository  ├─────┤ Drizzle││
diff --git a/doc/dev/servers/inference_bridge.rst b/doc/dev/servers/inference_bridge.rst
@@ -1,3 +1,5 @@
+.. _inference_bridge:
+
 =====================================
 graphcap Inference Bridge Architecture
 =====================================
@@ -69,7 +71,7 @@ Architecture Diagram
             │                                  │                     │
             │                                  │   AI Providers      │
             ▼                                  │                     │
-    ┌───────────────┐                         └─────────────────────┘
+    ┌───────────────┐                          └─────────────────────┘
     │  Data Service │
     │               │
     └───────┬───────┘
diff --git a/doc/dev/servers/media_server.rst b/doc/dev/servers/media_server.rst
@@ -1,3 +1,5 @@
+.. _media_server:
+
 =================================
 graphcap Media Server Architecture
 =================================
@@ -38,8 +40,8 @@ Architecture Components
 .. code-block:: text
 
    ┌─────────────────────────────────────────────────────┐
-   │                   Media Server                       │
-   │                                                      │
+   │                   Media Server                      │
+   │                                                     │
    │   ┌─────────────┐    ┌───────────────┐              │
    │   │             │    │               │              │
    │   │  Express    ├────┤   Services    │              │
diff --git a/doc/dev/workspaces.rst b/doc/dev/workspaces.rst
diff --git a/doc/getting_started/configuration.rst b/doc/getting_started/configuration.rst
@@ -3,69 +3,14 @@
 Configuration
 ============
 
-Initial Setup
-------------
+When you first open `localhost:32200`, you will find the main page of graphcap Studio:
 
-Graphcap provides a setup script to help you configure your environment and provider settings. 
-You can run the setup using:
+.. image:: static/graphcap_Studio_home.png
+   :alt: graphcap Studio home page
 
-.. code-block:: bash
-   task setup 
+The Server Connections will be Completed, but the Providers must be configured for graphcap to work correctly.
 
+Clicking on the "Configure Providers" button will open a modal that contains specific instructions on how to set up any providers that are currently used by graphcap.
 
-To run without reinstalling the venv, you can run:
-
-.. code-block:: bash
-   uv run python -m src.scripts
-
-This interactive script will:
-
-1. Create or update your ``.env`` file with provider settings
-2. Create or update your provider configuration in ``workspace/config/provider.config.toml``
-
-Environment Variables
--------------------
-
-The setup script will help you configure the following environment variables based on your 
-selected providers:
-
-- ``HUGGING_FACE_HUB_TOKEN``: API token for Hugging Face Hub
-- ``OPENAI_API_KEY``: API key for OpenAI services
-- ``GOOGLE_API_KEY``: API key for Google services
-- ``VLLM_BASE_URL``: Base URL for vLLM service
-- ``OLLAMA_BASE_URL``: Base URL for Ollama service
-
-Provider Configuration
---------------------
-
-The provider configuration file (``workspace/config/provider.config.toml``) defines settings for 
-each enabled provider. 
-
-Updating Configuration
---------------------
-
-You can rerun the setup script at any time to update your configuration:
-
-.. code-block:: bash
-
-   uv run python -m src.scripts
-
-The script will:
-
-- Detect existing configuration files
-- Ask for permission before overwriting
-- Preserve existing settings when updating
-- Allow you to enable/disable providers
-- Update API keys and settings as needed
-
-.. warning::
-   Be careful when overwriting existing configuration files. 
-   The setup script will ask for confirmation before making changes.
-
-Configuration Location
---------------------
-
-- Environment variables: ``.env`` in the project root
-- Provider configuration: ``workspace/config/provider.config.toml``
-
-These files are automatically loaded when running Graphcap services.
+.. image:: static/graphcap_Studio_provider_setup.png
+   :alt: graphcap Studio provider setup modal
diff --git a/doc/getting_started/datasets.rst b/doc/getting_started/datasets.rst
@@ -8,28 +8,30 @@ This guide will help you manage a dataset in the Graphcap UI.
 Creating a New Dataset
 ----------------------
 
-1. Visit ``localhost:32300`` to access the Graphcap web interface.
+1. Visit ``localhost:32200`` to access the Graphcap web interface.
 
-2. Click on the ``Gallery`` link on the right side. The Gallery defaults to the Carousel View and the ``os_img`` Dataset. 
+2. Click on the ``Datasets`` icon on the left side. The left drawer will open and you will see the current Datasets available to you.
 
-3. On the left side of the Gallery screen, next to Datasets, click on the ``New Dataset`` button. A ``Create New Dataset`` window will popup.
+3. Click on the ``Create Dataset`` button. A ``Create New Dataset`` window will popup.
 
-4. Type in the name of the dataset and press the ``Create dataset`` button. Use only letters, numbers, underscores, and hyphens. This will create a folder in the ``workspace/datasets/local`` folder, and this location will be referenced in future steps.
+4. Type in the name of the dataset and press the ``Create Dataset`` button. Use only letters, numbers, underscores, and hyphens. 
 
-If you need to cancel out of creating the dataset, click the ``Cancel`` button in the popup to return to the Gallery screen.
+If you need to cancel out of creating the dataset, click the ``Cancel`` button in the popup to return to the previous screen.
 
 Deleting a Dataset
 ------------------
 
-1. In the Gallery screen, either hover over or select the dataset you wish to delete.
+1. Click on the ``Datasets`` icon on the left side. The left drawer will open and you will see the current Datasets available to you.
 
-2. Click on the "hamburger" menu (the three vertical dots) that appear on the dataset. A small dialogue option will appear with ``Delete Dataset``.
+2. Hover over or select the dataset you wish to delete.
 
-3. Click on ``Delete Dataset``. A separate "Delete Dataset" window will popup, asking for you to confirm deletion of the dataset.
+3. Click on the "hamburger" menu (the three vertical dots) that appear on the dataset. A small dialogue option will appear with ``Delete Dataset``.
 
-4. To confirm deletion, click the ``Delete Dataset`` button in the popup.
+4. Click on ``Delete Dataset``. A separate "Delete Dataset" window will popup, asking for you to confirm deletion of the dataset.
 
-If you need to cancel the deletion, click the ``Cancel`` button in the popup to return to the Gallery screen.
+5. To confirm deletion, click the ``Delete Dataset`` button in the popup.
+
+If you need to cancel the deletion, click the ``Cancel`` button in the popup to return to the previous screen.
 
 Adding Images to a Dataset
 ---------------------------------
@@ -42,13 +44,21 @@ In a blank dataset, "No images found" will be shown, with a button to upload ima
 
 3. Select the image or images to upload, and click ``Open``.
 
+You can also drag-and-drop images to the dataset. Simply drag the image from a file browser and drop it over the ``Upload`` button.
+
 Deleting Images from a Dataset
 ------------------------------
 
 1. In either Carousel View or Grid View, select the image to delete.
 
 2. In the top right of the Image Editor, click the trashcan icon to delete the image.
 
+3. A confirmation modal will open, asking if you are sure you want to delete the image.
+
+4. To confirm deletion, click the ``Delete Image`` button in the modal.
+
+If you need to cancel the deletion, click the ``Cancel`` button in the modal to return to the previous screen.
+
 Editing Images in a Dataset
 ---------------------------
 
diff --git a/doc/getting_started/index.rst b/doc/getting_started/index.rst
@@ -11,8 +11,7 @@ This guide will help you get up and running with Graphcap. Follow these steps in
 
    configuration
    docker_override
-   workspaces
-   hello_world
+
 
 Quick Start
 ----------
@@ -23,24 +22,28 @@ Quick Start
 
       task setup
 
-2. Configure Docker settings if needed (see :ref:`docker_override`)
+2. Change the values for the following environment variables to ensure that your installation is secure:
+
+- POSTGRES_USER
+- POSTGRES_PASSWORD
+- ENCRYPTION_KEY
 
-3. Start the services:
+3. Configure Docker settings if needed (see :ref:`docker_override`)
+
+4. Start the services:
 
    .. code-block:: bash
 
       task start
 
-4. Visit ``localhost:32300`` to access the web interface
-
-5. Try the hello world example (see :ref:`hello_world`)
+5. Visit ``localhost:32200`` to access the web interface
 
 System Requirements
 -----------------
 
 - Docker and Docker Compose
 - Python 3.11 or higher
-- uv package manager
-- task runner
+- uv package manager (https://docs.astral.sh/uv/)
+- Task runner (https://taskfile.dev/)
 
 For detailed instructions on each component, follow the guides in the table of contents above.
diff --git a/doc/getting_started/static/graphcap_Studio_home.png b/doc/getting_started/static/graphcap_Studio_home.png
diff --git a/doc/getting_started/static/graphcap_Studio_provider_setup.png b/doc/getting_started/static/graphcap_Studio_provider_setup.png
diff --git a/doc/index.rst b/doc/index.rst
@@ -7,26 +7,32 @@ Welcome to graphcap's documentation!
 Alpha Testing
 ============
 
-## graphcap Project Overview for Alpha Testing
-
-**What is graphcap?**
+graphcap Project Overview for Alpha Testing
+-------------------------------------------
+Welcome to the alpha testing phase of **graphcap**! We are excited to have you on board as we refine and enhance this innovative captioning application. This document provides an overview of the project, its core features, and the goals for this alpha testing phase.
 
+*What is graphcap?*
+-------------------
 graphcap is an open-source, distributed captioning application designed under the Open Model Initiative. Its primary purpose is to generate detailed, insightful captions and analyses of images by leveraging multiple analytical perspectives. 
 The application utilizes directed acyclic graph structures to capture complex relationships within images, facilitating diverse, context-rich interpretations.
 
-### Core Features
+*Core Features*
+-------------------
 - **Multi-Perspective Captioning:** graphcap applies specialized analytical perspectives—such as formal artistic critique, emotional sentiment, storytelling, and temporal analysis—to generate comprehensive captions.
 - **Distributed Processing:** Designed to operate efficiently in distributed environments, allowing for scalable, community-based computational resources.
 - **Model Flexibility:** Supports integration with multiple Vision-Language Models (VLMs), enabling comparative analysis and ensuring adaptability across varied captioning tasks.
 - **OMI-Compatible:** graphcap is designed to be compatible with the Open Model Initiative data repository, allowing for easy integration with our open source image dataset.
 
-### Alpha Testing Goals
+*Alpha Testing Goals*
+-------------------
 - Evaluate system stability and performance across diverse hardware and software environments.
 - Collect feedback on caption accuracy, perspective usefulness, and overall usability.
 - Identify critical bugs and areas for improvement in functionality and user experience.
 
-### Participating in Alpha Testing
+*Participating in Alpha Testing*
+-----------------------------------
 Participants in the alpha test will:
+
 - Test the application in their local or preferred computing environment.
 - Provide structured feedback via surveys and discussions.
 - Engage collaboratively in community discussions to shape future graphcap development.
@@ -43,11 +49,8 @@ Getting Started
    :caption: Getting Started Guide
 
    getting_started/index
-   getting_started/hello_world
    getting_started/configuration
    getting_started/datasets
-   getting_started/caption_pipeline
-   getting_started/workspaces
    getting_started/docker_override
 
 User Interface
@@ -59,6 +62,28 @@ User Interface
 
    ui/action_drawers
 
+Concepts
+========
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Concepts
+
+   concepts/perspectives
+
+Development
+===========
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Development Documentation
+
+   dev/architecture
+   dev/servers/data_service
+   dev/servers/inference_bridge
+   dev/servers/media_server
+   dev/caption_pipeline
+
 Indices and tables
 ==================
 
diff --git a/doc/ui/action_drawers.rst b/doc/ui/action_drawers.rst
@@ -3,7 +3,7 @@ Action Drawers
 
 graphcap Studio now features collapsible action drawers on both sides of the interface for quick access to configuration and tools.
 
-.. image:: /static/images/action-drawers.png
+.. image:: action_drawers/static/action-drawers.png
    :alt: graphcap Studio action drawers showing left and right panels
    :align: center
    :width: 100%
@@ -13,7 +13,7 @@ Left Action Drawer
 
 The left drawer provides access to common configuration options and feature flags:
 
-* Always present in the interface
+* Optional visibility based on context
 * Contains feature toggles and standard configuration options
 * Designed for frequent access to common settings
 * Collapsible to maximize workspace when needed
diff --git a/doc/ui/action_drawers/static/action-drawers.png b/doc/ui/action_drawers/static/action-drawers.png

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+.. _perspectives:`
	`2`	`+`
`1`	`3`	`===========================`
`2`	`4`	`Perspectives in graphcap`
`3`	`5`	`===========================`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+.. _architecture:`
	`2`	`+`
`1`	`3`	`=================================`
`2`	`4`	`graphcap Architecture Overview`
`3`	`5`	`=================================`