Update documentation and add missing dependencies

.github/workflows/test-docs.yml

@@ -14,4 +14,4 @@ jobs:
     with:
       node-version: 20  # The node version needs to stay in sync with .readthedocs.yml
       python-version: '3.11'  # This needs to stay in sync with .readthedocs.yml and the tox config in pyproject.toml
-      tox-env-array: '["docs"]'  # TODO: add "doctests" environment
+      tox-env-array: '["docs"]'  # TODO: , "doctests"]'

CHANGELOG.md

@@ -18,6 +18,14 @@ Valid subsections within a version are:
 
 Things to be included in the next release go here.
 
+### Fixed
+
+- Added missing dependencies to `pyproject.toml`.
+
+### Changed
+
+- Updated all documentation links to use the proper URLs and fixed Readme badges.
+
 ---
 
 ## v0.1.0 (2024-09-11)
@@ -35,5 +43,3 @@ Things to be included in the next release go here.
 ### Added
 
 - First release of `TekHSI`!
-
----

README.md

@@ -4,8 +4,8 @@
 | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Testing**       | [![Code testing status](https://github.com/tektronix/TekHSI/actions/workflows/test-code.yml/badge.svg?branch=main)](https://github.com/tektronix/TekHSI/actions/workflows/test-code.yml) [![Docs testing status](https://github.com/tektronix/TekHSI/actions/workflows/test-docs.yml/badge.svg?branch=main)](https://github.com/tektronix/TekHSI/actions/workflows/test-docs.yml) [![Coverage status](https://codecov.io/gh/tektronix/TekHSI/branch/main/graph/badge.svg)](https://codecov.io/gh/tektronix/TekHSI)                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | **Code Quality**  | [![CodeQL status](https://github.com/tektronix/TekHSI/actions/workflows/codeql-analysis.yml/badge.svg?branch=main)](https://github.com/tektronix/TekHSI/actions/workflows/codeql-analysis.yml) [![CodeFactor grade](https://www.codefactor.io/repository/github/tektronix/TekHSI/badge)](https://www.codefactor.io/repository/github/tektronix/TekHSI) [![pre-commit status](https://results.pre-commit.ci/badge/github/tektronix/TekHSI/main.svg)](https://results.pre-commit.ci/latest/github/tektronix/TekHSI/main)                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| **Package**       | [![PyPI: Package status](https://img.shields.io/pypi/status/TekHSI?logo=pypi)](https://pypi.org/project/TekHSI/) [![PyPI: Latest release version](https://img.shields.io/pypi/v/TekHSI?logo=pypi)](https://pypi.org/project/TekHSI/) [![PyPI: Supported Python versions](https://img.shields.io/pypi/pyversions/TekHSI?logo=python)](https://pypi.org/project/TekHSI/) [![PyPI: Downloads](https://pepy.tech/badge/TekHSI)](https://pepy.tech/project/TekHSI) [![License: Apache 2.0](https://img.shields.io/pypi/l/TekHSI)](https://github.com/tektronix/TekHSI/blob/main/LICENSE.md) [![Package build status](https://github.com/tektronix/TekHSI/actions/workflows/package-build.yml/badge.svg?branch=main)](https://github.com/tektronix/TekHSI/actions/workflows/package-build.yml) [![PyPI upload status](https://github.com/tektronix/TekHSI/actions/workflows/package-release.yml/badge.svg?branch=main)](https://github.com/tektronix/TekHSI/actions/workflows/package-release.yml) |
-| **Documentation** | [![ReadtheDocs Status](https://img.shields.io/readthedocs/TekHSI/stable?logo=readthedocs)](https://tekhsi.readthedocs.io/stable)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| **Package**       | [![PyPI: Package status](https://img.shields.io/pypi/status/TekHSI?logo=pypi)](https://pypi.org/project/TekHSI/) [![PyPI: Latest release version](https://img.shields.io/pypi/v/TekHSI?logo=pypi)](https://pypi.org/project/TekHSI/) [![PyPI: Supported Python versions](https://img.shields.io/pypi/pyversions/TekHSI?logo=python)](https://pypi.org/project/TekHSI/) [![PyPI: Downloads](https://pepy.tech/badge/TekHSI)](https://pepy.tech/project/TekHSI) [![License: Apache 2.0](https://img.shields.io/pypi/l/tekhsi)](https://github.com/tektronix/TekHSI/blob/main/LICENSE.md) [![Package build status](https://github.com/tektronix/TekHSI/actions/workflows/package-build.yml/badge.svg?branch=main)](https://github.com/tektronix/TekHSI/actions/workflows/package-build.yml) [![PyPI upload status](https://github.com/tektronix/TekHSI/actions/workflows/package-release.yml/badge.svg?branch=main)](https://github.com/tektronix/TekHSI/actions/workflows/package-release.yml) |
+| **Documentation** | [![ReadtheDocs Status](https://img.shields.io/readthedocs/tekhsi/stable?logo=readthedocs)](https://tekhsi.readthedocs.io)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | **Code Style**    | [![Test style: pytest](https://img.shields.io/badge/test%20style-pytest-blue)](https://github.com/pytest-dev/pytest) [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-black)](https://docs.astral.sh/ruff/formatter/) [![Docstring style: google](https://img.shields.io/badge/docstring%20style-google-tan)](https://google.github.io/styleguide/pyguide.html)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | **Linting**       | [![pre-commit enabled](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit) [![Docstring formatter: docformatter](https://img.shields.io/badge/docstring%20formatter-docformatter-tan)](https://github.com/PyCQA/docformatter)[![Linter: pylint](https://img.shields.io/badge/linter-pylint-purple)](https://github.com/pylint-dev/pylint)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
@@ -53,7 +53,7 @@ In summary, if you need a reliable and efficient way to transfer data between yo
 
 ## Documentation
 
-See the full documentation at <https://TekHSI.readthedocs.io/stable/>
+See the full documentation at <https://TekHSI.readthedocs.io>
 
 ## Maintainers
 

mkdocs.yml

@@ -119,7 +119,7 @@ plugins:
             show_category_heading: false
             show_symbol_type_heading: true
             show_symbol_type_toc: false
-          import:  # TODO: import tm_data_types objects here
+          import:
             - url: https://docs.python.org/3/objects.inv
               domains: [std, py]
             - url: https://typing-extensions.readthedocs.io/en/stable/objects.inv
@@ -130,6 +130,8 @@ plugins:
               domains: [std, py]
             - url: https://docs.python-requests.org/en/stable/objects.inv
               domains: [std, py]
+            - url: https://tm-data-types.readthedocs.io/stable/objects.inv
+              domains: [std, py]
   - spellcheck:
       known_words: known_words.txt
       skip_files: [CHANGELOG.md, reference/*]

pyproject.toml

@@ -39,7 +39,7 @@ classifiers = [
   "Topic :: System :: Hardware :: Hardware Drivers"
 ]
 description = "Transfer waveforms from Tektronix Oscilloscopes using the High-Speed Interface."
-documentation = "https://TekHSI.readthedocs.io/stable/"
+documentation = "https://TekHSI.readthedocs.io"
 homepage = "https://pypi.org/project/TekHSI/"
 keywords = [
   "Tektronix",
@@ -53,6 +53,7 @@ repository = "https://github.com/tektronix/TekHSI"
 version = "0.1.0"
 
 [tool.poetry.dependencies]
+grpcio = "^1.51.3"
 numpy = [
   {python = "^3.9", version = "^1.26"},
   {python = "^3.8, <3.12", version = "^1.24"}
@@ -114,7 +115,6 @@ tomli = "^2.0.1"
 
 [tool.poetry.group.tests.dependencies]
 coverage = "^7.5.0"
-grpcio = "^1.51.3"
 linkchecker = "^10.0.0"
 psutil = "^6.0.0"
 pytest = "^8.2.0"

tests/conftest.py

@@ -5,6 +5,7 @@
 
 from abc import ABC
 from io import StringIO
+from pathlib import Path
 from typing import List
 
 import grpc
@@ -16,6 +17,8 @@
 from tekhsi._tek_highspeed_server_pb2_grpc import ConnectStub
 from tekhsi.tek_hsi_connect import TekHSIConnect
 
+PROJECT_ROOT_DIR = Path(__file__).parent.parent
+
 
 class DerivedWaveform(Waveform, ABC):
     @property

tests/test_docs.py

@@ -0,0 +1,79 @@
+"""Test for the documentation."""
+
+import os
+import shlex
+import subprocess
+import sys
+import time
+
+from importlib.util import find_spec
+from pathlib import Path
+from typing import Generator
+
+import pytest
+
+from conftest import PROJECT_ROOT_DIR
+
+
+@pytest.fixture(name="docs_server")
+def fixture_docs_server(site_dir: str) -> Generator[str, None, None]:
+    """Serve the documentation site."""
+    port = f"8{sys.version_info.major}{sys.version_info.minor}"
+    cmd = [sys.executable, "-m", "http.server", port, "--directory", site_dir]
+    with subprocess.Popen(  # noqa: S603
+        cmd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    ) as server_process:
+        time.sleep(1)  # wait for server to start
+
+        yield f"http://127.0.0.1:{port}/"
+
+        server_process.terminate()  # stop the server
+        try:
+            server_process.wait(timeout=10)  # Wait up to 10 seconds for the server to terminate
+        except subprocess.TimeoutExpired:
+            server_process.kill()  # Force kill if it doesn't terminate in time
+
+
+@pytest.fixture(name="site_dir", scope="session")
+def fixture_site_dir(pytestconfig: pytest.Config) -> str:
+    """Create the site directory path for testing."""
+    site_path = (
+        Path(__file__).parent.parent / f".site_{sys.version_info.major}{sys.version_info.minor}/"
+    ).resolve()
+    if xml_path := pytestconfig.getoption("xmlpath"):
+        site_path = (Path(xml_path).parent / ".site_html/").resolve()  # pyright: ignore[reportArgumentType]
+    site_path.mkdir(parents=True, exist_ok=True)
+    return site_path.as_posix()
+
+
+@pytest.fixture(scope="module", autouse=True)
+def _docs_tests_setup() -> Generator[None, None, None]:  # pyright: ignore [reportUnusedFunction]
+    """Setup for docs tests.."""
+    starting_directory = os.getcwd()
+    try:
+        os.chdir(PROJECT_ROOT_DIR)
+        yield
+    finally:
+        os.chdir(starting_directory)
+
+
+@pytest.mark.docs
+@pytest.mark.slow
+@pytest.mark.skipif(find_spec("mkdocs") is None, reason="The mkdocs package is not installed.")
+class TestDocs:  # pylint: disable=no-self-use
+    """A collection of documentation tests."""
+
+    @pytest.mark.order(1)
+    def test_docs_html(self, site_dir: str) -> None:
+        """Test creating html documentation."""
+        subprocess.check_call(shlex.split(f"mkdocs build --verbose --site-dir={site_dir}"))  # noqa: S603
+
+    @pytest.mark.order(2)
+    @pytest.mark.depends(on=["test_docs_html"])
+    def test_docs_linkcheck(self, docs_server: str) -> None:
+        """Run the linkcheck test for the documentation."""
+        subprocess.check_call(  # noqa: S603
+            shlex.split(f"linkchecker --config=docs/.linkchecker.ini {docs_server}")
+        )