Update package to point to ReadtheDocs for official documentation (#201)

* fix: Update imports so that dataclasses is only being imported once in the dm_config_parser.py module * fix: Update docs to enable building on readthedocs * docs: Update contribution guide to properly render hints and notes. * docs: Updated contribution guide to explain how to build the docs. * docs: Update the link to the source code to point to the main branch when building the "latest" docs on readthedocs. * docs: Update changelog to indicate the switch from GitHub Pages to ReadtheDocs for documentation hosting.
tektronix · May 3, 2024 · fb22432 · fb22432
1 parent 6868730
commit fb22432
Show file tree

Hide file tree

Showing 6 changed files with 58 additions and 34 deletions.
diff --git 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
@@ -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
@@ -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 <https://tektronix.github.io/tm_devices/>
+See the full documentation at <https://tm-devices.readthedocs.io/stable/>
 
 ## Maintainers
 

diff --git a/docs/generate_api_pages.py b/docs/generate_api_pages.py
@@ -32,7 +32,7 @@
         source_link = (
             f'<div class="top-right-link" markdown="1">'
             f'<a href="{{{{ config.repo_url }}}}'
-            f'/blob/{{{{ package_version }}}}/src/'
+            f'/blob/{{{{ git_ref }}}}/src/'
             f'{"/".join(module_path.parts)}.py">[python source code]</a>'
             f'</div>\n\n'
         )

diff --git 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
@@ -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",