From 1512913d7cdcd3875233d60ddd3ab6c0505244e5 Mon Sep 17 00:00:00 2001 From: Nicholas Felt Date: Thu, 2 May 2024 10:22:34 -0700 Subject: [PATCH 1/6] fix: Update imports so that dataclasses is only being imported once in the dm_config_parser.py module --- src/tm_devices/components/dm_config_parser.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/tm_devices/components/dm_config_parser.py b/src/tm_devices/components/dm_config_parser.py index d214e8c1..b73a8b0b 100644 --- a/src/tm_devices/components/dm_config_parser.py +++ b/src/tm_devices/components/dm_config_parser.py @@ -7,7 +7,6 @@ import os import pathlib -from dataclasses import dataclass from types import MappingProxyType from typing import ( Any, @@ -43,7 +42,7 @@ @runtime_checkable -@dataclass +@dataclasses.dataclass class _DataclassProtocol(Protocol): """A Protocol class to allow for type hinting things that accept generic dataclasses.""" From e13b63a37f61d000796c31db3579bf231fd48309 Mon Sep 17 00:00:00 2001 From: Nicholas Felt Date: Thu, 2 May 2024 16:45:53 -0700 Subject: [PATCH 2/6] fix: Update docs to enable building on readthedocs --- .readthedocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.readthedocs.yml b/.readthedocs.yml index 55017b1b..2e3693c8 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -4,6 +4,7 @@ build: os: ubuntu-22.04 tools: python: '3.11' # This needs to stay in sync with pyproject.toml and any CI scripts + nodejs: '20' # This needs to stay in sync with any CI scripts python: install: - requirements: docs/requirements.txt From ab226ebc4601688c9b61bfa3b1d82bcbdd967cd6 Mon Sep 17 00:00:00 2001 From: Nicholas Felt Date: Fri, 3 May 2024 09:37:04 -0700 Subject: [PATCH 3/6] docs: Update contribution guide to properly render hints and notes. --- CONTRIBUTING.md | 54 ++++++++++++++++++++++++------------------------- README.md | 4 ++-- pyproject.toml | 2 +- 3 files changed, 29 insertions(+), 31 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b1603f20..18061810 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -68,10 +68,9 @@ recommended IDE for package development is 1. Set up commit signing, see [GitHub's documentation](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification) for details. - ```{hint} - All commits going into the main repository are required to be signed, so make sure - to set up commit signing before starting to make changes. - ``` + !!! hint + All commits going into the main repository are required to be signed, so make sure + to set up commit signing before starting to make changes. 2. Fork `tm_devices` into a new repository. @@ -109,19 +108,19 @@ recommended IDE for package development is 6. When you're done making changes, check that your changes conform to any code formatting requirements and pass any tests. - ````{note} - Always remember to activate the virtual environment before attempting to run tests or other code. - ```console - # Linux - source .venv/bin/activate + !!! note + Always remember to activate the virtual environment before attempting to run tests or other code. - # Windows - .venv\Scripts\activate.bat - ``` - ```` + ```console + # Linux + source .venv/bin/activate + + # Windows + .venv\Scripts\activate.bat + ``` - To run full static code analysis, tests, and documentation validation - (running this prior to opening a pull request is highly recommended, but it is **very slow**): + (running this prior to opening a pull request is highly recommended, but it is slow): ```console tox -p @@ -145,12 +144,11 @@ recommended IDE for package development is tox -e tests ``` - ```{note} - Two html outputs are generated: + !!! note + Two html outputs are generated: - - Code coverage report: `.results_tests/htmlcov/index.html` - - Test results: `.results_tests/results.html` - ``` + - Code coverage report: `.results_tests/htmlcov/index.html` + - Test results: `.results_tests/results.html` 7. Commit and push your changes, then open a pull request from the fork back into the main repository. @@ -174,16 +172,16 @@ recommended IDE for package development is To update the required python packages and commit hooks run the following commands: -````{note} -Always remember to activate the virtual environment before attempting to run tests or other code. -```console -# Linux -source .venv/bin/activate +!!! note + Always remember to activate the virtual environment before attempting to run tests or other code. -# Windows -.venv\Scripts\activate.bat -``` -```` + ```console + # Linux + source .venv/bin/activate + + # Windows + .venv\Scripts\activate.bat + ``` ```console python scripts/update_development_dependencies.py diff --git a/README.md b/README.md index 30da4981..cb1cabb8 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ | **Testing** | [![Code testing status](https://github.com/tektronix/tm_devices/actions/workflows/test-code.yml/badge.svg?branch=main)](https://github.com/tektronix/tm_devices/actions/workflows/test-code.yml) [![Docs testing status](https://github.com/tektronix/tm_devices/actions/workflows/test-docs.yml/badge.svg?branch=main)](https://github.com/tektronix/tm_devices/actions/workflows/test-docs.yml) [![Coverage status](https://codecov.io/gh/tektronix/tm_devices/branch/main/graph/badge.svg)](https://codecov.io/gh/tektronix/tm_devices) | | **Code Quality** | [![CodeQL status](https://github.com/tektronix/tm_devices/actions/workflows/codeql-analysis.yml/badge.svg?branch=main)](https://github.com/tektronix/tm_devices/actions/workflows/codeql-analysis.yml) [![CodeFactor grade](https://www.codefactor.io/repository/github/tektronix/tm_devices/badge)](https://www.codefactor.io/repository/github/tektronix/tm_devices) [![pre-commit status](https://results.pre-commit.ci/badge/github/tektronix/tm_devices/main.svg)](https://results.pre-commit.ci/latest/github/tektronix/tm_devices/main) | | **Package** | [![PyPI: Package status](https://img.shields.io/pypi/status/tm_devices?logo=pypi)](https://pypi.org/project/tm_devices/) [![PyPI: Latest release version](https://img.shields.io/pypi/v/tm_devices?logo=pypi)](https://pypi.org/project/tm_devices/) [![PyPI: Supported Python versions](https://img.shields.io/pypi/pyversions/tm_devices?logo=python)](https://pypi.org/project/tm_devices/) [![PyPI: Downloads](https://pepy.tech/badge/tm-devices)](https://pepy.tech/project/tm_devices) [![License: Apache 2.0](https://img.shields.io/pypi/l/tm_devices)](https://tinyurl.com/tek-tm-devices/LICENSE.md) [![Package build status](https://github.com/tektronix/tm_devices/actions/workflows/package-build.yml/badge.svg?branch=main)](https://github.com/tektronix/tm_devices/actions/workflows/package-build.yml) [![PyPI upload status](https://github.com/tektronix/tm_devices/actions/workflows/package-release.yml/badge.svg?branch=main)](https://github.com/tektronix/tm_devices/actions/workflows/package-release.yml) | -| **Documentation** | | +| **Documentation** | [![ReadtheDocs Status](https://img.shields.io/readthedocs/tm-devices/stable?logo=readthedocs)](https://tm-devices.readthedocs.io/stable) | | **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) [![Type Checker: pyright](https://img.shields.io/badge/type%20checker-pyright-yellowgreen)](https://github.com/RobertCraigie/pyright-python) [![Linter: pylint](https://img.shields.io/badge/linter-pylint-purple)](https://github.com/pylint-dev/pylint) [![Linter: Ruff](https://img.shields.io/badge/linter-ruff-purple)](https://github.com/charliermarsh/ruff) | @@ -163,7 +163,7 @@ _Software Solution Support Levels_ ## Documentation -See the full documentation at +See the full documentation at ## Maintainers diff --git a/pyproject.toml b/pyproject.toml index 2f149e9b..895882e9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -49,7 +49,7 @@ classifiers = [ "Topic :: System :: Hardware :: Hardware Drivers" ] description = "Manage connections and interactions with Test & Measurement devices." -documentation = "https://tektronix.github.io/tm_devices/" +documentation = "https://tm-devices.readthedocs.io/stable/" homepage = "https://pypi.org/project/tm_devices/" keywords = [ "REST API", From 5b0fe081f013ef886b8ff802bf1c0a503310f8ad Mon Sep 17 00:00:00 2001 From: Nicholas Felt Date: Fri, 3 May 2024 09:49:31 -0700 Subject: [PATCH 4/6] docs: Updated contribution guide to explain how to build the docs. --- CONTRIBUTING.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 18061810..f4adee43 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -150,6 +150,24 @@ recommended IDE for package development is - Code coverage report: `.results_tests/htmlcov/index.html` - Test results: `.results_tests/results.html` + - To just build the documentation: + + ```console + tox -e docs + ``` + + !!! hint + To view the documentation locally you will need to first build and then serve the site using one of the following methods: + + ```console + mkdocs serve --clean --no-livereload + ``` + + ```console + tox -e docs + python -m http.server -d .results_docs + ``` + 7. Commit and push your changes, then open a pull request from the fork back into the main repository. From 73f9c5dbdab54d3254b5a0395370fda54d27f6d0 Mon Sep 17 00:00:00 2001 From: Nicholas Felt Date: Fri, 3 May 2024 10:35:23 -0700 Subject: [PATCH 5/6] docs: Update the link to the source code to point to the main branch when building the "latest" docs on readthedocs. --- docs/generate_api_pages.py | 2 +- docs/macros.py | 11 +++++++++-- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/generate_api_pages.py b/docs/generate_api_pages.py index c660e3b0..1ebcc24b 100644 --- a/docs/generate_api_pages.py +++ b/docs/generate_api_pages.py @@ -32,7 +32,7 @@ source_link = ( f'
' f'[python source code]' f'
\n\n' ) diff --git a/docs/macros.py b/docs/macros.py index 1b4028a2..07d37bdf 100644 --- a/docs/macros.py +++ b/docs/macros.py @@ -1,6 +1,7 @@ """Macros for the documentation.""" import inspect +import os import pathlib import re @@ -187,8 +188,14 @@ def define_env(env: MacrosPlugin) -> None: pathlib.Path(f"{pathlib.Path(__file__).parents[1]}") / "pyproject.toml", "rb" ) as file_handle: pyproject_data = tomli.load(file_handle) - env.variables["package_version"] = "v" + pyproject_data["tool"]["poetry"]["version"] - + package_version = "v" + pyproject_data["tool"]["poetry"]["version"] + git_ref = "main" if os.getenv("READTHEDOCS_VERSION") == "latest" else package_version + + # Add a variable that points to the latest version of the package + env.variables["package_version"] = package_version + # Add a variable that points to either the latest version tag or the main branch depending + # on where/when the docs are being built. + env.variables["git_ref"] = git_ref # Add the auto_class_diagram macro env.macro(class_diagram, "auto_class_diagram") # pyright: ignore[reportUnknownMemberType] # Add the create_repo_link macro From b1d1508ec775b064a340a992fe2f9f3ca394f55b Mon Sep 17 00:00:00 2001 From: Nicholas Felt Date: Fri, 3 May 2024 10:41:17 -0700 Subject: [PATCH 6/6] docs: Update changelog to indicate the switch from GitHub Pages to ReadtheDocs for documentation hosting. --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c6521a3..12e7ae56 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,7 @@ Things to be included in the next release go here. - Switched from using `sphinx` to `mkdocs` for building the documentation. This enables building the documentation in under 10 minutes while using less than 6 GB of RAM and saving almost 2 GB of disk space. Fixes [#77](https://github.com/tektronix/tm_devices/issues/77). +- Switched from GitHub Pages to ReadtheDocs for official documentation hosting. ### Fixed