Add tox environment for doctest (#1870)

* test

* use py312 to build docs

.github/workflows/ci.yml

@@ -35,18 +35,14 @@ 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: |
         sudo apt-get -y install linux-modules-extra-$(uname -r)
         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

.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:

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::
 

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:

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