Merge pull request hed-standard#1211 from VisLab/remove_vis

Added HED assistant to docs

Author: VisLab

docs/_templates/base.html

@@ -0,0 +1,36 @@
+{% extends "!base.html" %}
+
+{%- block scripts %}
+  {{ super() }}
+
+  <!-- OSA Chat Widget (HED Assistant)
+       Privacy Note: This widget sends page content to an external AI service when
+       allowPageContext is enabled. The widget provides contextual help for HEDTools documentation.
+       Data sent: Page text content, user questions
+       Service: OSA Chat Widget (osa-demo.pages.dev)
+  -->
+  <script>
+    // Define config before the widget script loads
+    window.osaChatConfig = {
+      communityId: 'hed',
+      title: 'HED Assistant',
+      initialMessage: 'Questions about HED or Python HEDTools? Ask me!',
+      placeholder: 'Questions about Python HEDTools?',
+      suggestedQuestions: [
+        'How do I install the Python HEDTools?',
+        'How do I validate a HED string using the Python HEDTools?',
+        'How do I run the HEDTools hedpy command line tool?',
+        'What tools are available?'
+      ],
+      widgetInstructions: 'User is on the Python HEDTools documentation most likely looking for how to use these tools',
+      showExperimentalBadge: true,
+      allowPageContext: true,
+      pageContextDefaultEnabled: true
+    };
+  </script>
+  <script src="https://osa-demo.pages.dev/osa-chat-widget.js"
+        crossorigin="anonymous"
+        defer
+        onload="window.OSAChatWidget && window.OSAChatWidget.setConfig(window.osaChatConfig)"></script>
+{%- endblock scripts %}
+

docs/index.rst

@@ -25,16 +25,8 @@ Python HEDTools features
 * **NWB support**: Read and write HED annotations in NWB files using `ndx-hed <https://www.hedtags.org/ndx-hed>`_
 * **Multiple formats**: Work with JSON sidecars, TSV files, Excel spreadsheets
 
-Getting started
----------------
-
-.. toctree::
-   :maxdepth: 2
-
-   Overview <overview>
-
-Programming with HEDTools
--------------------------
+User guide
+----------
 
 .. toctree::
    :maxdepth: 2

docs/overview.md

@@ -3,54 +3,93 @@
 description: Complete user guide for Python HEDTools - validation, BIDS 
   integration, analysis, and command-line tools for HED annotations
 keywords: HED tutorial, Python guide, validation examples, BIDS datasets, 
-  sidecar files, command-line interface, Jupyter notebooks
+  sidecar files, command-line interface, Jupyter notebooks, HED overview, event 
+  descriptors, neuroscience, schema
 ---
 ```
 
 # Python HEDTools guide
 
-```{index} user guide, tutorial, getting started
+```{index} user guide, tutorial, getting started, HED, Hierarchical Event Descriptors
 ```
 
-This guide provides step-by-step instructions for using the HED Python tools for validation, BIDS integration, and analysis.
-
-## Quick links
-
-- 📚 [API Reference](api/index.html)
-- 📓 [Jupyter notebooks](https://github.com/hed-standard/hed-python/tree/main/examples)
-- 🐛 [GitHub issues](https://github.com/hed-standard/hed-python/issues)
-- 🎓 [HED resources](https://www.hedtags.org/hed-resources)
-- 📖 [HED specification](https://www.hedtags.org/hed-specification)
-- 🌐 [Web tools](https://hedtools.org/hed)
+HED (Hierarchical Event Descriptors) is a framework for systematically describing events and experimental metadata in machine-actionable form. This guide provides comprehensive documentation for using the HED Python tools for validation, BIDS integration, and analysis.
 
 ## Table of contents
 
-1. [Getting started](#getting-started)
-2. [Working with HED schemas](#working-with-hed-schemas)
-3. [Validating HED strings](#validating-hed-strings)
-4. [Working with BIDS datasets](#working-with-bids-datasets)
-5. [Working with sidecars](#working-with-sidecars)
-6. [Jupyter notebooks](#jupyter-notebooks)
-7. [Command-line tools](#command-line-tools)
-8. [Best practices](#best-practices)
-9. [Troubleshooting](#troubleshooting)
+01. [What is HED?](#what-is-hed)
+02. [Getting started](#getting-started)
+03. [Working with HED schemas](#working-with-hed-schemas)
+04. [Validating HED strings](#validating-hed-strings)
+05. [Working with BIDS datasets](#working-with-bids-datasets)
+06. [Working with sidecars](#working-with-sidecars)
+07. [Jupyter notebooks](#jupyter-notebooks)
+08. [Command-line tools](#command-line-tools)
+09. [Best practices](#best-practices)
+10. [Troubleshooting](#troubleshooting)
 
 ## Getting started
 
+```{index} installation, pip, PyPI
+```
+
 ### Installation
 
-Install HEDTools from PyPI:
+#### From PyPI (recommended)
+
+Install the latest stable release:
 
 ```bash
 pip install hedtools
 ```
 
-For the latest development version from GitHub:
+**Note**: The PyPI package includes the core hedtools library but **not the example Jupyter notebooks**. To access the notebooks, see the options below.
+
+#### For Jupyter notebook examples
+
+The example notebooks are only available in the GitHub repository. Choose one of these options:
+
+**Option 1: Clone the full repository**
+
+```bash
+git clone https://github.com/hed-standard/hed-python.git
+cd hed-python
+pip install -e .[examples]
+# Notebooks are in: examples/
+```
+
+**Option 2: Download just the examples directory**
+
+```bash
+svn export https://github.com/hed-standard/hed-python/trunk/examples
+cd examples
+pip install hedtools jupyter notebook
+```
+
+See [examples/README.md](https://github.com/hed-standard/hed-python/tree/main/examples) for detailed notebook documentation.
+
+#### From GitHub (latest development version)
 
 ```bash
 pip install git+https://github.com/hed-standard/hed-python/@main
 ```
 
+#### For development
+
+Clone the repository and install in editable mode:
+
+```bash
+git clone https://github.com/hed-standard/hed-python.git
+cd hed-python
+pip install -e .
+```
+
+#### Python requirements
+
+- **Python 3.10 or later** is required
+- Core dependencies: pandas, numpy, defusedxml, openpyxl
+- Jupyter support: Install with `pip install jupyter notebook`
+
 ### Basic example
 
 Here's a simple example to get you started with HED validation:
@@ -826,6 +865,21 @@ print(get_cache_directory())
 
 ### Getting help
 
+#### Documentation resources
+
+- **[API reference](api/index.html)**: Detailed function and class documentation
+- **[HED specification](https://www.hedtags.org/hed-specification)**: Formal annotation rules
+- **[HED resources](https://www.hedtags.org/hed-resources)**: HED tutorials and guides
+- **[HED online tools](https://hedtools.org/hed)**: Web-based interface requiring no programming
+- **[Example datasets](https://github.com/hed-standard/hed-examples)**: HED-annotated example datasets
+
+#### Support
+
+- **Issues and bugs**: Open an [issue](https://github.com/hed-standard/hed-python/issues) on GitHub
+- **Questions and ideas**: Contribute to the [HED organization discussions](https://github.com/orgs/hed-standard/discussions)
+- **Online validation**: Try [HED online tools](https://hedtools.org/hed) for web-based access
+- **Contact**: Email [hed.maintainers@gmail.com](mailto:hed.maintainers@gmail.com)
+
 #### Before opening an issue
 
 1. Try the [online tools](https://hedtools.org) to isolate the problem
@@ -841,10 +895,3 @@ Include:
 - Minimal code example that reproduces the problem
 - Full error traceback
 - Expected vs actual behavior
-
-#### Additional resources
-
-- **HED specification**: [www.hedtags.org/hed-specification](https://www.hedtags.org/hed-specification)
-- **HED resources**: [www.hedtags.org](https://www.hedtags.org/hed-resources)
-- **HED online tools**: [hedtools.org/hed](https://hedtools.org/hed)
-- **Example datasets**: [hed-examples](https://github.com/hed-standard/hed-examples/datasets)