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
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b1603f20..f4adee43 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,29 @@ 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`
+
+ - 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.
@@ -174,16 +190,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** | [](https://github.com/tektronix/tm_devices/actions/workflows/test-code.yml) [](https://github.com/tektronix/tm_devices/actions/workflows/test-docs.yml) [](https://codecov.io/gh/tektronix/tm_devices) |
| **Code Quality** | [](https://github.com/tektronix/tm_devices/actions/workflows/codeql-analysis.yml) [](https://www.codefactor.io/repository/github/tektronix/tm_devices) [](https://results.pre-commit.ci/latest/github/tektronix/tm_devices/main) |
| **Package** | [](https://pypi.org/project/tm_devices/) [](https://pypi.org/project/tm_devices/) [](https://pypi.org/project/tm_devices/) [](https://pepy.tech/project/tm_devices) [](https://tinyurl.com/tek-tm-devices/LICENSE.md) [](https://github.com/tektronix/tm_devices/actions/workflows/package-build.yml) [](https://github.com/tektronix/tm_devices/actions/workflows/package-release.yml) |
-| **Documentation** | |
+| **Documentation** | [](https://tm-devices.readthedocs.io/stable) |
| **Code Style** | [](https://github.com/pytest-dev/pytest) [](https://docs.astral.sh/ruff/formatter/) [](https://google.github.io/styleguide/pyguide.html) |
| **Linting** | [](https://github.com/pre-commit/pre-commit) [](https://github.com/PyCQA/docformatter) [](https://github.com/RobertCraigie/pyright-python) [](https://github.com/pylint-dev/pylint) [](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/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'\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
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",