diff --git a/.github/workflows/test-docs.yml b/.github/workflows/test-docs.yml index f906703..2fcf1fa 100644 --- a/.github/workflows/test-docs.yml +++ b/.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"]' diff --git a/CHANGELOG.md b/CHANGELOG.md index 5faa30d..05c1f88 100644 --- a/CHANGELOG.md +++ b/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`! - ---- diff --git a/README.md b/README.md index be9bcda..4928f4b 100644 --- a/README.md +++ b/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 +See the full documentation at ## Maintainers diff --git a/mkdocs.yml b/mkdocs.yml index 34d00fb..69b3886 100644 --- a/mkdocs.yml +++ b/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/*] diff --git a/pyproject.toml b/pyproject.toml index e351cb5..754a352 100644 --- a/pyproject.toml +++ b/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" diff --git a/tests/conftest.py b/tests/conftest.py index 1a8f360..54e7352 100644 --- a/tests/conftest.py +++ b/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 diff --git a/tests/test_docs.py b/tests/test_docs.py new file mode 100644 index 0000000..66e2a13 --- /dev/null +++ b/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}") + )