Enable insiders documentation features

.readthedocs.yaml

@@ -5,6 +5,8 @@ build:
   tools:
     python: '3.11'  # This needs to stay in sync with the tox config in pyproject.toml and any CI scripts
     nodejs: '20'  # This needs to stay in sync with any CI scripts
+  jobs:
+    post_install: [python scripts/install_insiders_packages.py]
 python:
   install:
     - requirements: docs/requirements.txt

docs/_static/css/theme_overrides.css

@@ -123,16 +123,15 @@ span.doc-object-name {
 }
 
 /* Customize link color */
-a.autorefs, a.autorefs code {
+a.autorefs, a.autorefs code, .rst-content .admonition a.autorefs code {
     color: dodgerblue !important;
 }
 
-a.autorefs:hover, a.autorefs:hover code {
+a.autorefs:hover, a.autorefs:hover code, .rst-content .admonition a.autorefs:hover code {
     color: #d600d6 !important;
 }
 
-/* Hide all ToC entries for auto-generated command parts. */
-li:has(> a[href^="gen_"]),
-li:has(> a[href*="/gen_"]) {
-    display: none;
+/* Remove the mermaidTooltip */
+.mermaidTooltip {
+    display: none !important;
 }

docs/_templates/mkdocstrings/python/readthedocs/children.html.jinja

@@ -16,13 +16,11 @@ Context:
         {%- for item in item_list %}
             {%- if item.docstring %}
                 <tr>
-                    {%- filter stash_crossref(length=item.canonical_path|length) -%}
                     <td>
-                        <span data-autorefs-optional-hover="{{ item.canonical_path }}">
+                        <autoref identifier="{{ item.canonical_path }}" optional hover>
                             <code class="subpackage-summary-link-text">{{ item.name }}</code>
-                        </span>
+                        </autoref>
                     </td>
-                    {%- endfilter -%}
                     <td>{{ item.docstring.parsed[0].value.split("\n")[0]|convert_markdown(heading_level, html_id) }}</td>
                 </tr>
             {%- endif %}

docs/_templates/mkdocstrings/python/readthedocs/class.html.jinja

@@ -0,0 +1,50 @@
+{# TODO: Drop Python 3.8: remove this file after updating to newer versions of mkdocstrings-python #}
+{% extends "_base/class.html.jinja" %}
+        {% block inheritance_diagram %}
+          {#- Inheritance diagram block.
+
+          This block renders the inheritance diagram for the class,
+          using Mermaid syntax and a bit of JavaScript to make the nodes clickable,
+          linking to the corresponding class documentation.
+          -#}
+          {% if config.show_inheritance_diagram and class.bases %}
+            {% macro edges(class) %}
+              {% for base in class.resolved_bases %}
+                {{ base.path }} --> {{ class.path }}
+                {{ edges(base) }}
+              {% endfor %}
+            {% endmacro %}
+            <div style="display: none">
+              <autoref identifier="{{ class.path }}" optional id="mermaid-link-{{ class.path }}"></autoref>
+                {% for base in class.mro() %}
+                  <autoref identifier="{{ base.path }}" optional id="mermaid-link-{{ base.path }}"></autoref>
+                {% endfor %}
+            </div>
+            <div class="mermaid" id="mermaid-diagram-{{ class.path }}">
+              flowchart LR
+              {{ class.path }}[{{ class.name }}]
+              {% for base in class.mro() %}
+              {{ base.path }}[{{ base.name }}]
+              {% endfor %}
+
+              {{ edges(class) | safe }}
+
+              click {{ class.path }} href "" "{{ class.path }}"
+              {% for base in class.mro() %}
+              click {{ base.path }} href "" "{{ base.path }}"
+              {% endfor %}
+            </div>
+            <!--suppress ES6ConvertVarToLetConst -->
+              <script>
+              var diagram = document.getElementById('mermaid-diagram-{{ class.path }}');
+              diagram.innerHTML = diagram.innerHTML.replace(/click ([\w.]+) href "" "\1"/g, function(match, nodeID, offset) {
+                try {
+                  const link = document.getElementById("mermaid-link-" + nodeID).href;
+                  return `click ${nodeID} href "${link}" "${nodeID}"`
+                } catch (e) {
+                  return '';
+                }
+              });
+            </script>
+          {% endif %}
+        {% endblock inheritance_diagram %}

mkdocs.yml

@@ -88,36 +88,45 @@ plugins:
       use_default: true
       inline_refs: none
       markdown_links: true
-  - mermaid2
+  - mermaid2:
+      javascript: https://unpkg.com/[email protected]/dist/mermaid.min.js
   - mkdocstrings:  # additional customization takes place in docs/generate_api_pages.py
       enable_inventory: true
       custom_templates: docs/_templates/mkdocstrings
       handlers:
         python:  # see https://mkdocstrings.github.io/python/usage/
           paths: [src]
           options:
-            docstring_options:
-              ignore_init_summary: true
-              trim_doctest_flags: true
-            merge_init_into_class: true
-            members_order: alphabetical
-            show_inheritance_diagram: true
-            inherited_members: true
+            # General options
+            show_inheritance_diagram: true  # INSIDERS FEATURE
             show_source: false  # a link is included at the top of each page
-            docstring_section_style: list
-            filters: ['!^_', ^__init__]
-            summary: true
-            show_signature_annotations: true
-            separate_signature: true
-            line_length: 100
-            signature_crossrefs: true
-            show_labels: true
+            # Headings options
             heading_level: 1
             show_root_heading: true
             show_root_full_path: false
             show_category_heading: false
             show_symbol_type_heading: true
             show_symbol_type_toc: false
+            # Members options
+            inherited_members: true
+            members_order: alphabetical
+            filters: ['!^_', ^__init__]
+            summary: false  # Currently implemented with custom templates
+            show_labels: true
+            # Docstrings options
+            docstring_options:
+              ignore_init_summary: true
+              trim_doctest_flags: true
+            docstring_section_style: list
+            merge_init_into_class: true
+            relative_crossrefs: true  # INSIDERS FEATURE
+            scoped_crossrefs: true  # INSIDERS FEATURE
+            # Signature options
+            line_length: 100
+            modernize_annotations: false  # INSIDERS FEATURE (if the source code annotations format changes, update this to true)
+            show_signature_annotations: true
+            signature_crossrefs: true
+            separate_signature: true
           import:
             - url: https://docs.python.org/3/objects.inv
               domains: [std, py]

pyproject.toml

@@ -68,7 +68,7 @@ scipy = [
 ]
 
 [tool.poetry.group.dev.dependencies]
-docutils = "^0.20"  # TODO: remove this when the minimum Python version is >=3.9
+docutils = "^0.20"  # TODO: Drop Python 3.8: remove this when the minimum Python version is >=3.9
 docutils-stubs = "^0.0.22"
 matplotlib = [
   {python = ">=3.9", version = "^3.8"},
@@ -111,8 +111,10 @@ mkdocs-spellcheck = "^1.1.0"
 mkdocstrings = "^0.26.1"
 mkdocstrings-python = "^1.10.2"
 nodeenv = "^1.9.1"
+packaging = "^24.2"
 pygments = "^2.17.2"
 pymdown-extensions = "^10.8.1"
+requests = "^2.32.3"
 symspellpy = "^6.7.7"
 tomli = "^2.0.1"
 
@@ -264,7 +266,6 @@ ignore = [
   "ANN",  # flake8-annotations  # TODO: enable this
   "ANN401",  # Dynamically typed expressions (typing.Any) are disallowed in *args and **kwargs
   "COM812",  # Trailing comma missing (handled by formatter)
-  "D",  # pydocstyle  # TODO: enable this
   "EM101",  # Exception must not use a string literal, assign to variable first  # TODO: enable this
   "EM102",  # Exception must not use an f-string literal, assign to variable first (covered by TRY003)
   "FA100",  # Missing `from __future__ import annotations`, but uses ...  # TODO: enable this
@@ -386,21 +387,33 @@ commands_pre =
 
 [testenv:docs]
 basepython = {env:DOC_PYTHON_VERSION}
+passenv =
+    GITHUB_PAT
 deps =
     -rdocs/requirements.txt
 commands_pre =
     nodeenv --python-virtualenv --clean-src
+    python scripts/install_insiders_packages.py
 commands =
     python -c "import shutil; shutil.rmtree('.results_{envname}', ignore_errors=True)"
     mkdocs --verbose build --site-dir .results_{envname}
 
 [testenv:doctests]
 basepython = {env:DOC_PYTHON_VERSION}
+passenv =
+    GITHUB_PAT
 deps =
     -rdocs/requirements.txt
     -rtests/requirements.txt
 commands_pre =
     nodeenv --python-virtualenv --clean-src
+    python scripts/install_insiders_packages.py
 commands =
     pytest -v -k "test_docs" --showlocals --junitxml={tox_root}/.results_{envname}/results.xml --self-contained-html --html={tox_root}/.results_{envname}/results.html
+
+[testenv:export-reqs]
+commands =
+    poetry export --without-hashes --without-urls --all-extras --only=docs --output=docs/requirements.txt
+    poetry export --without-hashes --without-urls --all-extras --only=tests --output=tests/requirements.txt
+    - pre-commit run -a requirements-txt-fixer
 """

scripts/install_insiders_packages.py

@@ -0,0 +1,133 @@
+"""Install insiders packages corresponding to currently installed versions of specified packages."""
+
+import importlib.metadata
+import logging
+import os
+import subprocess
+import sys
+
+from typing import List
+
+import requests
+
+from packaging.version import parse as parse_version
+
+logging.basicConfig(
+    level=getattr(logging, os.getenv("LOGGING_LEVEL", "INFO")),
+    format="[%(asctime)s] [%(levelname)8s] %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+PACKAGE_LIST = {
+    "mkdocstrings-python": "https://github.com/pawamoy-insiders/mkdocstrings-python",
+    "griffe": "https://github.com/pawamoy-insiders/griffe",
+}
+
+
+def get_github_tags(repo_url_str: str, github_token: str) -> List[str]:
+    """Get the tags for a GitHub repository.
+
+    Args:
+        repo_url_str: The URL of the GitHub repository.
+        github_token: The GitHub token to use for authentication.
+
+    Returns:
+        A list of tag names for the repository.
+    """
+    # Extract the owner and repository name from the URL
+    parts = repo_url_str.rstrip("/").split("/")
+    owner, repo = parts[-2], parts[-1]
+
+    try:
+        response = requests.get(
+            f"https://api.github.com/repos/{owner}/{repo}/tags",
+            headers={"Authorization": f"token {github_token}"},
+            timeout=30,
+        )
+        response.raise_for_status()  # Raise an exception for HTTP errors
+
+        tags = response.json()
+        return [tag["name"] for tag in tags]
+
+    except requests.exceptions.RequestException:
+        logger.error("Error getting tags for %s", repo_url_str)  # noqa: TRY400
+        return []
+
+
+def get_newest_matching_tag(current_version: str, tags: List[str]) -> str:
+    """Find the newest tag that starts with the given current version.
+
+    Args:
+        current_version: The current version of the package.
+        tags: A list of tag names.
+
+    Returns:
+        The newest tag that starts with the current version, or an empty string if none are found.
+    """
+    # Filter tags that start with the current version
+    matching_tags = [tag for tag in tags if tag.startswith(current_version)]
+
+    # Sort matching tags as version numbers in descending order
+    matching_tags.sort(key=parse_version, reverse=True)
+
+    return matching_tags[0] if matching_tags else ""
+
+
+def install_package(package_name: str, repo_url_str: str, tag: str, github_token: str) -> None:
+    """Install a package from a GitHub repository using a specific tag.
+
+    Args:
+        package_name: The name of the package to install.
+        repo_url_str: The HTTPS URL of the GitHub repository.
+        tag: The tag to install.
+        github_token: The GitHub token to use for authentication.
+    """
+    # Insert the token into the URL for authentication
+    repo_url_str = repo_url_str.replace("https://", f"https://{github_token}@")
+
+    install_url = f"{repo_url_str}.git@{tag}"
+    try:
+        logger.info("Installing %s from tag %s", package_name, tag)
+        subprocess.check_call(  # noqa: S603
+            [sys.executable, "-m", "pip", "install", f"git+{install_url}"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        logger.info("Successfully installed %s from tag %s", package_name, tag)
+    except subprocess.CalledProcessError:
+        logger.error("Failed to install %s from tag %s", package_name, tag)  # noqa: TRY400
+
+
+def main() -> None:
+    """Install insiders packages."""
+    if not (github_token := os.environ.get("GITHUB_PAT")):
+        logger.info(
+            "GITHUB_PAT environment variable is not set, no insiders packages will be installed."
+        )
+        return
+    for package, repo_url in PACKAGE_LIST.items():
+        logger.info("Processing %s", package)
+        try:
+            version = importlib.metadata.version(package)
+            logger.info("%s installed version is %s", package, version)
+        except importlib.metadata.PackageNotFoundError:
+            logger.warning("%s is not installed.", package)
+            version = None
+
+        if version and (package_tags := get_github_tags(repo_url, github_token)):
+            logger.info("Tags for %s: %s", package, package_tags)
+
+            if newest_tag := get_newest_matching_tag(version, package_tags):
+                logger.info(
+                    'Newest matching tag for %s version %s is "%s"',
+                    package,
+                    version,
+                    newest_tag,
+                )
+                install_package(package, repo_url, newest_tag, github_token)
+            else:
+                logger.info("No matching tags found for %s with version %s", package, version)
+
+
+if __name__ == "__main__":
+    main()

src/tm_data_types/__init__.py

@@ -1,9 +1,6 @@
 """tm_data_types.
 
 Read and write common Test & Measurement files.
-
-Examples:
-    >>>
 """
 
 from importlib.metadata import version

src/tm_data_types/datum/__init__.py

@@ -0,0 +1 @@
+"""A collection of data types."""

src/tm_data_types/datum/data_types.py

@@ -75,6 +75,7 @@ def type_max(
         data_format: The dtype to get the maximum extent of.
 
     Returns:
+        The maximum extent of the type.
     """
     dtype = _check_type(data_format)
     if issubclass(dtype.type, np.integer):

src/tm_data_types/datum/waveforms/__init__.py

@@ -0,0 +1 @@
+"""A collection of waveform data types."""

src/tm_data_types/files_and_formats/__init__.py

@@ -0,0 +1 @@
+"""A collection of classes encapsulating various file formats."""