Merge pull request #1169 from VisLab/add_examples

Updated the docs for hed-python

Author: VisLab

README.md

@@ -26,7 +26,7 @@ For simple validation or transformation tasks, use the online tools at [https://
 
 Browser-based validation (no data upload) is available at [https://www.hedtags.org/hed-javascript](https://www.hedtags.org/hed-javascript)
 
-A development version is available at: [https://hedtools.org/hed_dev](https://hedtools.org/hed_dev)
+A development version of the online tools is available at: [https://hedtools.org/hed_dev](https://hedtools.org/hed_dev)
 
 ### Python installation
 
@@ -49,12 +49,13 @@ pip install git+https://github.com/hed-standard/hed-python/@main
 ```python
 from hed import HedString, load_schema_version
 
+
 # Load the latest HED schema
 schema = load_schema_version("8.4.0")
 
 # Create and validate a HED string
-hed_string = HedString("Sensory-event, Visual-presentation, (Onset, (Red, Square))")
-issues = hed_string.validate(schema)
+hed_string = HedString("Sensory-event, Visual-presentation, (Onset, (Red, Square))", schema)
+issues = hed_string.validate()
 
 if issues:
     print(get_printable_issue_string(issues, title="Validation issues found"))
@@ -128,9 +129,9 @@ See [`examples/README.md`](examples/README.md) for more details.
 
 📖 **Full Documentation:** [https://www.hedtags.org/hed-python](https://www.hedtags.org/hed-python)
 
-- [User Guide](https://www.hedtags.org/hed-python/user_guide.html) - Usage instructions
-- [API Reference](https://www.hedtags.org/hed-python/api/index.html) - Detailed API documentation
-- [HED Specification](https://www.hedtags.org/hed-specification) - Full HED standard specification
+- [User guide](https://www.hedtags.org/hed-python/user_guide.html) - Usage instructions
+- [API reference](https://www.hedtags.org/hed-python/api/index.html) - Detailed API documentation
+- [HED specification](https://www.hedtags.org/hed-specification) - Full HED standard specification
 
 ### Building docs locally
 
@@ -179,28 +180,28 @@ black --workers 1 .
 
 **Exclusions:** Black automatically excludes `.venv/`, `__pycache__/`, auto-generated files (`hed/_version.py`), and external repos (`spec_tests/hed-examples/`, `spec_tests/hed-specification/`).
 
-**CI Integration:** All code is automatically checked for Black formatting in GitHub Actions. Run `black .` before committing to ensure your code passes CI checks.
+**CI integration:** All code is automatically checked for Black formatting in GitHub Actions. Run `black .` before committing to ensure your code passes CI checks.
 
-## Related Repositories
+## Related repositories
 
 The HED ecosystem consists of several interconnected repositories:
 
-| Repository                                                             | Description                                       |
-| ---------------------------------------------------------------------- | ------------------------------------------------- |
-| [hed-python](https://github.com/hed-standard/hed-python)               | Python validation and analysis tools (this repo)  |
-| [hed-web](https://github.com/hed-standard/hed-web)                     | Web interface and deployable Docker services      |
-| [hed-resources](https://github.com/hed-standard/hed-resources)         | Example code in Python and MATLAB + HED resources |
-| [hed-specification](https://github.com/hed-standard/hed-specification) | Official HED specification documents              |
-| [hed-schemas](https://github.com/hed-standard/hed-schemas)             | Official HED schema repository                    |
-| [ndx-hed](https://github.com/hed-standard/ndx-hed)                     | HED support for NWB                               |
-| [hed-javascript](https://github.com/hed-standard/hed-javascript)       | JavaScript HED validation tools                   |
+| Repository                                                             | Description                                      |
+| ---------------------------------------------------------------------- | ------------------------------------------------ |
+| [hed-python](https://github.com/hed-standard/hed-python)               | Python validation and analysis tools (this repo) |
+| [hed-web](https://github.com/hed-standard/hed-web)                     | Web interface and deployable Docker services     |
+| [hed-resources](https://github.com/hed-standard/hed-resources)         | Tutorials and other HED resources                |
+| [hed-specification](https://github.com/hed-standard/hed-specification) | Official HED specification documents             |
+| [hed-schemas](https://github.com/hed-standard/hed-schemas)             | Official HED schema repository                   |
+| [ndx-hed](https://github.com/hed-standard/ndx-hed)                     | HED support for NWB                              |
+| [hed-javascript](https://github.com/hed-standard/hed-javascript)       | JavaScript HED validation tools                  |
 
 ## Contributing
 
 We welcome contributions! Here's how you can help:
 
 1. **Report issues:** Use [GitHub Issues](https://github.com/hed-standard/hed-python/issues) for bug reports and feature requests
-2. **Submit pull requests (PRs):** PRs should target the `main` branch
+2. **Submit pull requests (PRs):** PRs should be from a non-main fork and target the `main` branch
 3. **Improve documentation:** Help us make HED easier to use
 4. **Share examples:** Contribute example code and use cases
 
@@ -229,7 +230,7 @@ python -m unittest tests/path/to/test_file.py
 python -m unittest tests.test_notebooks
 ```
 
-For detailed contribution guidelines, please see [CONTRIBUTING.md](CONTRIBUTING.md) (coming soon).
+For detailed contribution guidelines, please see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Configuration
 
@@ -267,6 +268,6 @@ HEDTools is licensed under the MIT License. See [LICENSE](LICENSE) for details.
 ## Support
 
 - [Documentation](https://www.hedtags.org/hed-python)
-- [GitHub Issues](https://github.com/hed-standard/hed-python/issues)
+- [GitHub issues](https://github.com/hed-standard/hed-python/issues)
 - [HED Homepage](https://www.hedtags.org)
-- Contact: hed-maintainers@gmail.com
+- Contact: [hed-maintainers@gmail.com](mailto:hed-maintainers@gmail.com)

docs/_static/custom.css

@@ -29,6 +29,14 @@ body[data-theme="dark"] .sidebar-quicklinks {
     border-color: #1a1a1a;
 }
 
+/* Auto mode with dark system preference */
+@media (prefers-color-scheme: dark) {
+    body:not([data-theme="light"]) .sidebar-quicklinks {
+        background-color: #0d0d0d;
+        border-color: #1a1a1a;
+    }
+}
+
 .sidebar-quicklinks h3 {
     margin-top: 0;
     margin-bottom: 0.5rem;
@@ -91,6 +99,16 @@ body[data-theme="dark"] .sidebar-search-container input {
     background-image: url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='%23cccccc' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'%3E%3C/circle%3E%3Cline x1='21' y1='21' x2='16.65' y2='16.65'%3E%3C/line%3E%3C/svg%3E") !important;
 }
 
+/* Auto mode with dark system preference */
+@media (prefers-color-scheme: dark) {
+    body:not([data-theme="light"]) .sidebar-search-container input {
+        background-color: #0d0d0d !important;
+        border: 1px solid #1a1a1a !important;
+        color: #e8e8e8 !important;
+        background-image: url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='%23cccccc' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'%3E%3C/circle%3E%3Cline x1='21' y1='21' x2='16.65' y2='16.65'%3E%3C/line%3E%3C/svg%3E") !important;
+    }
+}
+
 /* Make search icon visible */
 .sidebar-search-container input::placeholder {
     color: var(--color-foreground-muted) !important;

docs/_templates/quicklinks.html

@@ -6,5 +6,6 @@ <h3>Quick links</h3>
         <li><a href="https://www.hedtags.org/hed-schema-browser" target="_blank">HED schema browser</a></li>
         <li><a href="https://www.hedtags.org/hed-specification" target="_blank">HED specification</a></li>
         <li><a href="https://hedtools.org/hed" target="_blank">HED online tools</a></li>
+        <li><a href="https://hedtools.org/table-remodeler" target="_blank">Table-remodeler</a></li>
     </ul>
 </div>

docs/api/errors.rst

@@ -3,7 +3,7 @@ Errors
 
 Error handling and reporting classes for HED validation and processing.
 
-Error Types and Constants
+Error types and constants
 -------------------------
 
 HedExceptions
@@ -22,7 +22,7 @@ HedFileError
    :undoc-members:
    :show-inheritance:
 
-Error Reporting
+Error reporting
 ---------------
 
 ErrorHandler
@@ -33,7 +33,7 @@ ErrorHandler
    :undoc-members:
    :show-inheritance:
 
-Error Functions
+Error functions
 ~~~~~~~~~~~~~~~
 
 .. autofunction:: hed.errors.error_reporter.get_printable_issue_string
@@ -42,7 +42,7 @@ Error Functions
 
 .. autofunction:: hed.errors.error_reporter.replace_tag_references
 
-Error Types
+Error types
 -----------
 
 ValidationErrors

docs/api/index.rst

@@ -1,7 +1,7 @@
-API Reference
+API reference
 =============
 
-This section contains the complete API reference for HED Python Tools.
+This section contains the complete API reference for HED Python tools.
 
 .. toctree::
    :maxdepth: 2
@@ -12,10 +12,10 @@ This section contains the complete API reference for HED Python Tools.
    tools
    errors
 
-Core Modules Overview
+Core modules overview
 ---------------------
 
-The HED Python Tools package is organized into several key modules:
+The HED Python tools package is organized into several key modules:
 
 * **Models**: Core data structures for HED annotations and tags
 * **Schema**: HED schema management and validation

docs/api/models.rst

@@ -3,7 +3,7 @@ Models
 
 Core data models for working with HED data structures.
 
-Core Models
+Core models
 -----------
 
 The fundamental data structures for HED annotations and tags.
@@ -40,7 +40,7 @@ DefinitionDict
    :undoc-members:
    :show-inheritance:
 
-Input Models
+Input models
 ------------
 
 Models for handling different types of input data.

docs/api/schema.rst

@@ -3,7 +3,7 @@ Schema
 
 HED schema management and validation tools.
 
-Core Schema Classes
+Core schema classes
 -------------------
 
 HedSchema
@@ -62,24 +62,24 @@ HedSchemaSection
    :undoc-members:
    :show-inheritance:
 
-Schema IO and Caching
+Schema IO and caching
 ---------------------
 
-Schema Loading Functions
+Schema loading functions
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. automodule:: hed.schema.hed_schema_io
    :members: load_schema, load_schema_version, from_string, get_hed_xml_version, from_dataframes
    :undoc-members:
 
-Cache Management
+Cache management
 ~~~~~~~~~~~~~~~~
 
 .. automodule:: hed.schema.hed_cache
    :members: cache_xml_versions, get_hed_versions, set_cache_directory, get_cache_directory
    :undoc-members:
 
-Schema Constants
+Schema constants
 ----------------
 
 HedKey

docs/api/tools.rst

@@ -3,7 +3,7 @@ Tools
 
 Utility functions and data processing tools for HED operations.
 
-Analysis Tools
+Analysis tools
 --------------
 
 EventManager
@@ -54,7 +54,7 @@ FileDictionary
    :undoc-members:
    :show-inheritance:
 
-BIDS Tools
+BIDS tools
 ----------
 
 BidsDataset
@@ -97,7 +97,7 @@ BidsTabularFile
    :undoc-members:
    :show-inheritance:
 
-BIDS Utilities
+BIDS utilities
 ~~~~~~~~~~~~~~
 
 .. automodule:: hed.tools.bids.bids_util

docs/api/validator.rst

@@ -3,7 +3,7 @@ Validator
 
 Validation tools for HED data structures and annotations.
 
-Core Validator Classes
+Core validator classes
 ----------------------
 
 HedValidator
@@ -14,7 +14,7 @@ HedValidator
    :undoc-members:
    :show-inheritance:
 
-Specialized Validators
+Specialized validators
 ----------------------
 
 SidecarValidator
@@ -49,7 +49,7 @@ OnsetValidator
    :undoc-members:
    :show-inheritance:
 
-Validation Utilities
+Validation utilities
 --------------------
 
 ReservedChecker

docs/index.rst

@@ -7,9 +7,9 @@ Welcome to the HED Python tools documentation. This package provides comprehensi
    :maxdepth: 2
    :caption: Contents:
 
-   introduction
-   user_guide
-   api/index
+   Introduction <introduction>
+   User guide <user_guide>
+   API reference <api/index>
 
 Indices and tables
 ==================