Merge pull request #671 from VisLab/add_instructions

Updating Appendix A for new formats

Author: VisLab

.github/workflows/codespell.yml

@@ -22,12 +22,13 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: '3.10'
+          python-version: '3.12'
+          cache: 'pip'
 
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install codespell tomli
+          pip install -e ".[dev]"
           
       - name: Run Codespell
         run: codespell .

.github/workflows/deploy-docs.yml

@@ -35,7 +35,7 @@ jobs:
       - name: Install dependencies
         run: |
           pip install --upgrade pip
-          pip install -e ".[docs]"
+          pip install -e ".[dev]"
 
       - name: Cache Sphinx build
         uses: actions/cache@v4

.github/workflows/links.yaml

@@ -28,7 +28,7 @@ jobs:
       - name: Install dependencies
         run: |
           pip install --upgrade pip
-          pip install -e ".[docs]"
+          pip install -e ".[dev]"
 
       - name: Build documentation with Sphinx
         run: |

.github/workflows/mdformat.yaml

@@ -23,11 +23,12 @@ jobs:
         uses: actions/setup-python@v6
         with:
           python-version: '3.12'
+          cache: 'pip'
 
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install mdformat==0.7.22 mdformat-myst==0.2.2 mdformat-tables==1.0.0
+          pip install -e ".[dev]"
           
       - name: Run mdformat (check only)
         run: |

docs/source/Appendix_A.md

@@ -59,6 +59,7 @@
     "source_repository": "https://github.com/hed-standard/hed-specification/",
     "source_branch": "main",
     "source_directory": "docs/source/",
+    "navigation_with_keys": True,
 }
 
 # Configure sidebar to show logo, search, navigation, and quick links

docs/source/conf.py

@@ -4,11 +4,8 @@ HED specification
 .. sidebar:: Quick links  
 
    * `HED homepage <https://www.hedtags.org/>`_
-
    * `HED resources <https://www.hedtags.org/hed-resources/>`_
-
    * `HED schema browser <https://www.hedtags.org/hed-schema-browser/>`_
-
    * `HED online tools <https://hedtools.org/hed>`_
 
 
@@ -21,132 +18,44 @@ vocabularies. The HED ecosystem includes:
 - **Analysis tools** - Methods for searching and analyzing HED-annotated data
 - **Community schemas** - Domain-specific extensions to the base vocabulary
 
-Specification contents
-----------------------
-
-1. Introduction
-~~~~~~~~~~~~~~~
-:doc:`Introduction to HED <01_Introduction>` - Overview of the HED system and its applications.
-
-.. contents:: Chapter contents
-   :local:
-   :depth: 2
-
-- HED system overview
-- Integration with neuroimaging standards
-- Schema vocabulary
-- Getting started
-
-2. Terminology
-~~~~~~~~~~~~~~
-:doc:`Terminology <02_Terminology>` - Key concepts and definitions used throughout the specification.
-
-.. contents:: Chapter contents
-   :local:
-   :depth: 2
-
-- Character sets and restrictions
-- HED vocabulary terminology
-- Schema version naming
-- Tag specification
-
-3. HED formats
-~~~~~~~~~~~~~~
-:doc:`HED formats <03_HED_formats>` - Schema and annotation format specifications.
-
-.. contents:: Chapter contents
-   :local:
-   :depth: 2
-
-- Schema format
-- HED string format
-- Sidecar format
-- Assembly and validation
-
-4. Basic annotation
-~~~~~~~~~~~~~~~~~~~
-:doc:`Basic annotation <04_Basic_annotation>` - Fundamental annotation techniques and best practices.
-
-.. contents:: Chapter contents
-   :local:
-   :depth: 2
-
-- Annotation principles
-- Basic event markup
-- Event context
-- Temporal relationships
-
-5. Advanced annotation
-~~~~~~~~~~~~~~~~~~~~~~
-:doc:`Advanced annotation <05_Advanced_annotation>` - Complex annotation patterns and advanced features.
-
-.. contents:: Chapter contents
-   :local:
-   :depth: 2
-
-- Definitions
-- Temporal scope
-- Event structure
-- Advanced examples
-
-6. Infrastructure and tools
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-:doc:`Infrastructure and tools <06_Infrastructure_and_tools>` - HED ecosystem tools and services.
-
-.. contents:: Chapter contents
-   :local:
-   :depth: 2
-
-- HED tools overview
-- Validation services
-- Web-based tools
-- Programming interfaces
-
-7. Library schemas
-~~~~~~~~~~~~~~~~~~
-:doc:`Library schemas <07_Library_schemas>` - Domain-specific schema extensions.
-
-.. contents:: Chapter contents
-   :local:
-   :depth: 2
-
-- Library schema concept
-- Creating library schemas
-- Using library schemas
-- BIDS integration
-
-8. HED ontology
-~~~~~~~~~~~~~~~
-:doc:`HED ontology <08_HED_ontology>` - Ontological framework and mappings.
-
-.. contents:: Chapter contents
-   :local:
-   :depth: 2
-
-- Ontological foundations
-- Semantic relationships
-- External ontology mappings
-- Interoperability
-
-Appendices
-~~~~~~~~~~
-* :doc:`Appendix A <Appendix_A>` - Additional schema information
-* :doc:`Appendix B <Appendix_B>` - Error codes and validation rules
+Core specification
+------------------
+
+The core chapters provide the foundation for understanding and using HED.
 
 .. toctree::
-   :hidden:
-   :maxdepth: 3
+   :maxdepth: 2
 
    01_Introduction
    02_Terminology
    03_HED_formats
    04_Basic_annotation
    05_Advanced_annotation
+
+Advanced topics
+---------------
+
+These chapters cover specialized aspects of the HED ecosystem.
+
+.. toctree::
+   :maxdepth: 2
+
    06_Infrastructure_and_tools
    07_Library_schemas
    08_HED_ontology
+
+Reference materials
+-------------------
+
+Additional technical reference and validation information.
+
+.. toctree::
+   :maxdepth: 2
+
    Appendix_A
    Appendix_B
 
+Indices and tables
+------------------
 
 * :ref:`genindex`

docs/source/index.rst

@@ -49,29 +49,19 @@ packages = []  # This is a documentation-only project, no Python packages
 "*" = ["*.md", "*.rst", "*.txt", "*.yaml", "*.yml"]
 
 [project.optional-dependencies]
-docs = [
-    "sphinx>=7.1.0,<8.2.0",
-    "furo>=2023.9.10",
-    "myst-parser>=3.0.0",
-    "sphinx-design>=0.6.1",
-    "sphinx-copybutton>=0.5.2",
-    "linkify-it-py>=2.0.3",
-]
-quality = [
-    "linkchecker>=10.0.0",
-    "codespell>=2.0.0",
-]
 dev = [
-    # Documentation dependencies (from docs group)
-    "sphinx>=7.1.0",
-    "furo>=2023.9.10",
+    # Documentation dependencies
+    "sphinx>=7.1.0,<10.0.0",
+    "furo>=2024.1.29",
     "myst-parser>=3.0.0",
-    "sphinx-design>=0.6.1",
     "sphinx-copybutton>=0.5.2",
     "linkify-it-py>=2.0.3",
-    # Quality/dev dependencies (from quality group)
-    "linkchecker>=10.0.0",
-    "codespell>=2.0.0",
+    # Quality/development tools
+    "codespell>=2.2.0",
+    "ruff>=0.8.0",
+    "black[jupyter]>=26.1.0",
+    "mdformat>=0.7.0",
+    "mdformat-myst>=0.1.5",
 ]
 
 [project.urls]