From cc95a061caa165a707adafa7721ae660e6692c43 Mon Sep 17 00:00:00 2001 From: Kay Robbins <1189050+VisLab@users.noreply.github.com> Date: Sun, 25 Jan 2026 10:47:25 -0600 Subject: [PATCH 1/2] Updated the docs as part of integration --- .gitmodules | 2 +- CHANGELOG.md | 2 +- CONTRIBUTING.md | 3 ++- docs/_templates/sidebar/brand.html | 2 +- docs/api/index.rst | 4 ++-- docs/index.rst | 31 ++++++--------------------- docs/{introduction.md => overview.md} | 16 ++++++++------ docs/user_guide.md | 10 ++++----- examples/extract_json_template.ipynb | 6 +++--- 9 files changed, 31 insertions(+), 45 deletions(-) rename docs/{introduction.md => overview.md} (85%) diff --git a/.gitmodules b/.gitmodules index 957c17f5..354fe4dc 100644 --- a/.gitmodules +++ b/.gitmodules @@ -6,4 +6,4 @@ [submodule "spec_tests/hed-examples"] path = spec_tests/hed-examples url = https://github.com/hed-standard/hed-examples/ - branch = develop \ No newline at end of file + branch = main \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index dd14dc9c..78b318ca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -481,7 +481,7 @@ The primary purpose of this release was to correct the JSON format for HED schem # Release 0.1.0 June 20, 2022 -- First release on PyPI\`\`\` +- First release on PyPI ``` ``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index af0d9dc5..5c0b09d9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -334,7 +334,8 @@ Create an issue with: ## Questions? - **Documentation:** [https://www.hedtags.org/hed-python](https://www.hedtags.org/hed-python) +- **Discussions:** [HED Organization Discussions](https://github.com/orgs/hed-standard/discussions) - Ask questions, share ideas, and discuss HED-related topics - **Issues:** [GitHub Issues](https://github.com/hed-standard/hed-python/issues) -- **Email:** Kay.Robbins@utsa.edu +- **Email:** [hed.maintainers@gmail.com](mailto:hed.maintainers@gmail.com) Thank you for contributing to HEDTools! 🎉 diff --git a/docs/_templates/sidebar/brand.html b/docs/_templates/sidebar/brand.html index 8d955881..e893cec2 100644 --- a/docs/_templates/sidebar/brand.html +++ b/docs/_templates/sidebar/brand.html @@ -2,5 +2,5 @@ {% block brand_content %} {{ super() }} -
HED Python tools
+
Python HEDTools
{% endblock brand_content %} diff --git a/docs/api/index.rst b/docs/api/index.rst index 115cca44..44c4ebc2 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -1,5 +1,5 @@ -API reference -============= +Python HEDTools API +=================== This section contains the complete API reference for HED Python tools. diff --git a/docs/index.rst b/docs/index.rst index 4631acab..f872e06a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,21 +1,6 @@ Python HEDTools =============== - -.. sidebar:: Quick links - - * `HED homepage `_ - - * `HED vocabularies `_ - - * `HED online tools `_ - - * `HED browser tools `_ - - * `HED organization `_ - - * `HED specification `_ - Welcome to the Python HEDTools documentation! This package provides comprehensive tools for working with **Hierarchical Event Descriptors (HED)** - a standardized framework for annotating events and experimental metadata in neuroscience and beyond. What is HED? @@ -41,7 +26,7 @@ Getting started .. toctree:: :maxdepth: 2 - Introduction + Overview Programming with HEDTools ------------------------- @@ -49,20 +34,18 @@ Programming with HEDTools .. toctree:: :maxdepth: 2 - User guide + Guide -API documentation ------------------ +Python HEDTools API +------------------- .. toctree:: :maxdepth: 2 - API reference + API -Indices and tables -================== +Index +===== * :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/introduction.md b/docs/overview.md similarity index 85% rename from docs/introduction.md rename to docs/overview.md index cfcb4fd9..e07e9928 100644 --- a/docs/introduction.md +++ b/docs/overview.md @@ -1,4 +1,4 @@ -# Introduction to HEDTools +# Python HEDTools overview ## What is HED? @@ -16,8 +16,10 @@ The **hedtools** Python package (`hed-python` repository) provides: - **Core validation** of HED annotations against schema specifications - **BIDS integration** for neuroimaging dataset processing +- **NWB support** for reading and writing HED annotations in NWB files using [ndx-hed](https://www.hedtags.org/ndx-hed) - **Analysis tools** for event summarization, temporal processing, and tag analysis - **HED schema tools** for validating, comparing and converting HED schemas +- **Multiple formats** support for JSON sidecars, TSV files, Excel spreadsheets - **Command-line interface** for scripting and automation - **Jupyter notebooks** for interactive analysis workflows @@ -101,8 +103,8 @@ pip install -e . ### Support -- **Issues and bugs**: Open an [**issue**](https://github.com/hed-standard/hed-python/issues) on GitHub -- **Questions**: Use GitHub issues +- **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/hedstandard/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) @@ -154,7 +156,7 @@ issues = sidecar.validate(schema) ## Next steps -- Explore the [**User guide**](user_guide.md) for detailed workflows -- Try the [**Jupyter notebooks**](https://github.com/hed-standard/hed-python/tree/main/examples) for interactive examples -- Check the [**API reference**](api/index.html) for complete function documentation -- Validate your data using the HED [**online tools**](https://hedtools.org/hed) or the HED [**browser-based tools**](https://www.hedtags.org/hed-javascript) +- Explore the [User guide](user_guide.md) for detailed workflows +- Try the [Jupyter notebooks](https://github.com/hed-standard/hed-python/tree/main/examples) for interactive examples +- Check the [Python HEDTools API](api/index.html) for complete function documentation +- Validate your data using the HED [online tools](https://hedtools.org/hed) or the HED [browser-based tools](https://www.hedtags.org/hed-javascript) diff --git a/docs/user_guide.md b/docs/user_guide.md index f2a0f294..c27f1928 100644 --- a/docs/user_guide.md +++ b/docs/user_guide.md @@ -1,4 +1,4 @@ -# The HEDTools user guide +# Python HEDTools guide This guide provides step-by-step instructions for using the HED Python tools for validation, BIDS integration, and analysis. @@ -9,7 +9,7 @@ This guide provides step-by-step instructions for using the HED Python tools for - 🐛 [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) -- 🌐 [Online tools](https://hedtools.org/hed) +- 🌐 [Web tools](https://hedtools.org/hed) ## Table of contents @@ -228,7 +228,7 @@ json_string = sidecar.get_as_json_string() ## Jupyter notebooks -The [**examples**](https://github.com/hed-standard/hed-python/tree/main/examples) directory in the GitHub [**hed-python**](https://github.com/hed-standard/hed-python) repository contains Jupyter notebooks for BIDS annotation workflows. These notebooks are **not included in the PyPI package**. +The [examples](https://github.com/hed-standard/hed-python/tree/main/examples) directory in the GitHub [hed-python](https://github.com/hed-standard/hed-python) repository contains Jupyter notebooks for BIDS annotation workflows. These notebooks are **not included in the PyPI package**. ### Available notebooks @@ -271,7 +271,7 @@ pip install hedtools jupyter notebook 5. **Merge back** (if using spreadsheet) - Convert spreadsheet back to JSON 6. **Validate** - Check for errors and iterate until valid -See the examples [**README**](https://github.com/hed-standard/hed-python/tree/main/examples) for detailed documentation of each notebook. +See the examples [README](https://github.com/hed-standard/hed-python/tree/main/examples) for detailed documentation of each notebook. ## Command-line tools @@ -581,7 +581,7 @@ hedpy schema add-ids /path/to/hed-schemas score 2.2.0 2. Convert to all formats and verify equivalence 3. Add HED IDs only once - they should remain stable 4. Generate ontology after IDs are added -5. Verify that the created ontology is valid using [**Protégé**](https://protege.stanford.edu/) +5. Verify that the created ontology is valid using [Protégé](https://protege.stanford.edu/) 6. Commit changes to version control before moving to stable release ______________________________________________________________________ diff --git a/examples/extract_json_template.ipynb b/examples/extract_json_template.ipynb index 7dba137e..5817c0a0 100644 --- a/examples/extract_json_template.ipynb +++ b/examples/extract_json_template.ipynb @@ -11,7 +11,7 @@ "General strategy for machine-actionable annotation using HED in BIDS is to create a single `events.json` sidecar file in the BIDS dataset root directory.\n", "Ideally, this sidecar will contain all the annotations needed for users to understand and analyze the data.\n", "\n", - "(See the [**BIDS annotation quickstart**](https://www.hedtags.org/hed-resources) for additional information on this strategy.)\n", + "(See the [BIDS annotation quickstart](https://www.hedtags.org/hed-resources) for additional information on this strategy.)\n", "\n", "This notebook shows how to create a JSON sidecar template from the information in all the event files in a BIDS dataset. To use this notebook, substitute the specifics of your BIDS dataset for the following variables:\n", "\n", @@ -27,9 +27,9 @@ "\n", "Typical `skip_columns` include the `onset`, `duration`, and `sample` columns, which have well-defined meanings according to BIDS. The `value_columns` just require a single annotation, applicable to each value in the column.\n", "\n", - "For additional information see the tutorial [**Create a JSON template**](https://hedtags.org/hed-resources/BidsAnnotationQuickstart.html#create-a-json-template) which illustrates the creation of a template from a single event file using the online tools.\n", + "For additional information see the tutorial [Create a JSON template](https://hedtags.org/hed-resources/BidsAnnotationQuickstart.html#create-a-json-template) which illustrates the creation of a template from a single event file using the online tools.\n", "\n", - "See [**Sidecar template extraction**](https://www.hedtags.org/hed-python/user_guide.html#sidecar-template-extraction) in the HEDTools documentation for an example of how to directly extract a template using command line tools." + "See [Sidecar template extraction](https://www.hedtags.org/hed-python/user_guide.html#sidecar-template-extraction) in the HEDTools documentation for an example of how to directly extract a template using command line tools." ] }, { From 0ad48972c1c27be07f9a42a97c5becf2e5fc0e84 Mon Sep 17 00:00:00 2001 From: Kay Robbins <1189050+VisLab@users.noreply.github.com> Date: Sun, 25 Jan 2026 11:23:16 -0600 Subject: [PATCH 2/2] Updated the links --- docs/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/overview.md b/docs/overview.md index e07e9928..7c78256b 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -104,7 +104,7 @@ pip install -e . ### 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/hedstandard/discussions) +- **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)