From a39e63eac51ae7fbb872fa997aa4730113ba766c Mon Sep 17 00:00:00 2001
From: zariiii9003 <52598363+zariiii9003@users.noreply.github.com>
Date: Wed, 9 Oct 2024 16:09:39 +0200
Subject: [PATCH] Add tox environment for doctest (#1870)

* test

* use py312 to build docs
---
 .github/workflows/ci.yml | 18 +++---------------
 .readthedocs.yml         |  2 +-
 doc/development.rst      |  3 +--
 doc/scripts.rst          |  4 ++++
 tox.ini                  | 15 ++++++++++++++-
 5 files changed, 23 insertions(+), 19 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b3e90b445..6291994a0 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -35,10 +35,6 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
         allow-prereleases: true
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install tox
     - name: Setup SocketCAN
       if: ${{ matrix.os == 'ubuntu-latest' }}
       run: |
@@ -46,7 +42,7 @@ jobs:
         sudo ./test/open_vcan.sh
     - name: Test with pytest via tox
       run: |
-        tox -e gh
+        pipx run tox -e gh
       env:
         # SocketCAN tests currently fail with PyPy because it does not support raw CAN sockets
         # See: https://foss.heptapod.net/pypy/pypy/-/issues/3809
@@ -131,18 +127,10 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: "3.10"
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install -e .[canalystii,gs_usb,mf4]
-        pip install -r doc/doc-requirements.txt
+        python-version: "3.12"
     - name: Build documentation
       run: |
-        python -m sphinx -Wan --keep-going doc build
-    - name: Run doctest
-      run: |
-        python -m sphinx -b doctest -W --keep-going doc build
+        pipx run tox -e docs
 
   build:
     name: Packaging
diff --git a/.readthedocs.yml b/.readthedocs.yml
index 32be9c7b5..dad8c28db 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -9,7 +9,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.10"
+    python: "3.12"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
diff --git a/doc/development.rst b/doc/development.rst
index c83f0f213..a8332eeb6 100644
--- a/doc/development.rst
+++ b/doc/development.rst
@@ -48,8 +48,7 @@ The unit tests can be run with::
 
 The documentation can be built with::
 
-    pip install -r doc/doc-requirements.txt
-    python -m sphinx -an doc build
+    pipx run tox -e docs
 
 The linters can be run with::
 
diff --git a/doc/scripts.rst b/doc/scripts.rst
index 520b19177..2d59b7528 100644
--- a/doc/scripts.rst
+++ b/doc/scripts.rst
@@ -12,12 +12,14 @@ Command line help, called with ``--help``:
 
 
 .. command-output:: python -m can.logger -h
+    :shell:
 
 
 can.player
 ----------
 
 .. command-output:: python -m can.player -h
+    :shell:
 
 
 can.viewer
@@ -52,9 +54,11 @@ By default the ``can.viewer`` uses the :doc:`/interfaces/socketcan` interface. A
 The full usage page can be seen below:
 
 .. command-output:: python -m can.viewer -h
+    :shell:
 
 
 can.logconvert
 --------------
 
 .. command-output:: python -m can.logconvert -h
+    :shell:
diff --git a/tox.ini b/tox.ini
index 1ca07a33f..1d4e88166 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,5 +1,4 @@
 [tox]
-isolated_build = true
 
 [testenv]
 deps =
@@ -30,6 +29,20 @@ passenv =
     PY_COLORS
     TEST_SOCKETCAN
 
+[testenv:docs]
+description = Build and test the documentation
+basepython = py312
+deps =
+    -r doc/doc-requirements.txt
+    gs-usb
+
+extras =
+    canalystii
+
+commands =
+    python -m sphinx -b html    -Wan --keep-going doc build
+    python -m sphinx -b doctest -W   --keep-going doc build
+
 
 [pytest]
 testpaths = test