From c188b3f5d852e6fa9a25808543726627889b0275 Mon Sep 17 00:00:00 2001 From: "Felt, Nicholas" Date: Wed, 11 Sep 2024 14:40:46 -0700 Subject: [PATCH 1/6] test: Add tests for documentation. Also, fix the link to the ReadtheDocs page --- .github/workflows/test-docs.yml | 2 +- README.md | 4 +- docs/known_words.txt | 1 + pyproject.toml | 2 +- tests/conftest.py | 5 +++ tests/test_docs.py | 79 +++++++++++++++++++++++++++++++++ 6 files changed, 89 insertions(+), 4 deletions(-) create mode 100644 tests/conftest.py create mode 100644 tests/test_docs.py diff --git a/.github/workflows/test-docs.yml b/.github/workflows/test-docs.yml index f906703..bc7aa22 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", "doctests"]' diff --git a/README.md b/README.md index 4e8a5f4..b060eff 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ | **Testing** | [![Code testing status](https://github.com/tektronix/tm_data_types/actions/workflows/test-code.yml/badge.svg?branch=main)](https://github.com/tektronix/tm_data_types/actions/workflows/test-code.yml) [![Docs testing status](https://github.com/tektronix/tm_data_types/actions/workflows/test-docs.yml/badge.svg?branch=main)](https://github.com/tektronix/tm_data_types/actions/workflows/test-docs.yml) [![Coverage status](https://codecov.io/gh/tektronix/tm_data_types/branch/main/graph/badge.svg)](https://codecov.io/gh/tektronix/tm_data_types) | | **Code Quality** | [![CodeQL status](https://github.com/tektronix/tm_data_types/actions/workflows/codeql-analysis.yml/badge.svg?branch=main)](https://github.com/tektronix/tm_data_types/actions/workflows/codeql-analysis.yml) [![CodeFactor grade](https://www.codefactor.io/repository/github/tektronix/tm_data_types/badge)](https://www.codefactor.io/repository/github/tektronix/tm_data_types) [![pre-commit status](https://results.pre-commit.ci/badge/github/tektronix/tm_data_types/main.svg)](https://results.pre-commit.ci/latest/github/tektronix/tm_data_types/main) | | **Package** | [![PyPI: Package status](https://img.shields.io/pypi/status/tm_data_types?logo=pypi)](https://pypi.org/project/tm_data_types/) [![PyPI: Latest release version](https://img.shields.io/pypi/v/tm_data_types?logo=pypi)](https://pypi.org/project/tm_data_types/) [![PyPI: Supported Python versions](https://img.shields.io/pypi/pyversions/tm_data_types?logo=python)](https://pypi.org/project/tm_data_types/) [![PyPI: Downloads](https://pepy.tech/badge/tm_data_types)](https://pepy.tech/project/tm_data_types) [![License: Apache 2.0](https://img.shields.io/pypi/l/tm_data_types)](https://github.com/tektronix/tm_data_types/blob/main/LICENSE.md) [![Package build status](https://github.com/tektronix/tm_data_types/actions/workflows/package-build.yml/badge.svg?branch=main)](https://github.com/tektronix/tm_data_types/actions/workflows/package-build.yml) [![PyPI upload status](https://github.com/tektronix/tm_data_types/actions/workflows/package-release.yml/badge.svg?branch=main)](https://github.com/tektronix/tm_data_types/actions/workflows/package-release.yml) | -| **Documentation** | [![ReadtheDocs Status](https://img.shields.io/readthedocs/tm_data_types/stable?logo=readthedocs)](https://tm_data_types.readthedocs.io/stable) | +| **Documentation** | [![ReadtheDocs Status](https://img.shields.io/readthedocs/tm_data_types/stable?logo=readthedocs)](https://tm-data-types.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) | @@ -64,7 +64,7 @@ waveform = read_file(file_path) ## Documentation -See the full documentation at +See the full documentation at ## Maintainers diff --git a/docs/known_words.txt b/docs/known_words.txt index 23e2040..bf4d7f2 100644 --- a/docs/known_words.txt +++ b/docs/known_words.txt @@ -19,6 +19,7 @@ socio styleguide sublicense tektronix +tm tm_data_types wfm www diff --git a/pyproject.toml b/pyproject.toml index da836c8..2185c9a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -36,7 +36,7 @@ classifiers = [ "Topic :: System :: Hardware :: Hardware Drivers" ] description = "Read and write common Test & Measurement data types." -documentation = "https://tm-data-types.readthedocs.io/stable/" +documentation = "https://tm-data-types.readthedocs.io" homepage = "https://pypi.org/project/tm_data_types/" keywords = [ "Tektronix", diff --git a/tests/conftest.py b/tests/conftest.py new file mode 100644 index 0000000..37269a5 --- /dev/null +++ b/tests/conftest.py @@ -0,0 +1,5 @@ +"""Pytest configuration file.""" + +from pathlib import Path + +PROJECT_ROOT_DIR = Path(__file__).parent.parent 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}") + ) From e664914f920b7e2d202e5fb129f4fe6abb476fb9 Mon Sep 17 00:00:00 2001 From: "Felt, Nicholas" Date: Wed, 11 Sep 2024 14:43:06 -0700 Subject: [PATCH 2/6] docs: Update changelog --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0fefdd1..08faee9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,10 @@ Valid subsections within a version are: Things to be included in the next release go here. +### Changed + +- Updated all documentation links to use the proper URL. + --- ## v0.1.0 (2024-09-11) From 3ed6006866293083bc9b403409a00faa8bf0e582 Mon Sep 17 00:00:00 2001 From: "Felt, Nicholas" Date: Wed, 11 Sep 2024 14:43:45 -0700 Subject: [PATCH 3/6] docs: Update changelog --- CHANGELOG.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 08faee9..65a5b0f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -43,5 +43,3 @@ Things to be included in the next release go here. ### Added - First release of `tm_data_types`! - ---- From 570fd3169529880498b2e2211f519161e675de2e Mon Sep 17 00:00:00 2001 From: "Felt, Nicholas" Date: Wed, 11 Sep 2024 15:28:06 -0700 Subject: [PATCH 4/6] build: add missing dependency --- pyproject.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pyproject.toml b/pyproject.toml index 2185c9a..6d3c58b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -61,6 +61,7 @@ numpy = [ ] pydantic = "^2.7.4" python = "^3.8" +python-dateutil = "^2.8.2" scipy = [ {python = "^3.9", version = "^1.12"}, {python = "^3.8, <3.12", version = "^1.10"} From 61029d8164b3c1fe5c73c52d182bf2da1cbfc419 Mon Sep 17 00:00:00 2001 From: "Felt, Nicholas" Date: Wed, 11 Sep 2024 15:33:41 -0700 Subject: [PATCH 5/6] ci: Don't run doctests just yet --- .github/workflows/test-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test-docs.yml b/.github/workflows/test-docs.yml index bc7aa22..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", "doctests"]' + tox-env-array: '["docs"]' # TODO: , "doctests"]' From 1e43c084581e86447852ce1efad8e24bd126e89a Mon Sep 17 00:00:00 2001 From: "Felt, Nicholas" Date: Wed, 11 Sep 2024 15:36:48 -0700 Subject: [PATCH 6/6] docs: Update changelog --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 65a5b0f..0c402c3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,10 @@ 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 URL.