fix readthedocs (RTD) public docsite, modernize some of the docs build/testing

.github/workflows/lint-and-test.yml

@@ -89,7 +89,7 @@ jobs:
 
     - name: Install dependencies
       if: steps.python.outputs.cache-hit != 'true'
-      run: poetry install --no-interaction --no-root --with dev
+      run: poetry install --no-interaction --no-root --with dev,docs
 
     - name: Install library
       run: poetry install --no-interaction

.readthedocs.yaml

@@ -8,13 +8,17 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.12"
+  jobs:
+    post_create_environment:
+      # Install poetry
+      # https://python-poetry.org/docs/#installing-manually
+      - pip install poetry==1.6.1
+      # Tell poetry to not use a virtual environment
+      - poetry config virtualenvs.create false
+    post_install:
+      # Install dependencies with 'docs' dependency group
+      # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
+      - poetry install --with docs
 
 sphinx:
-   configuration: docs/conf.py
-
-# Optionally declare the Python requirements required to build your docs
-python:
-  install:
-    - requirements: docs/requirements.txt
-    - method: pip
-      path: .
+  configuration: docs/conf.py

CONTRIBUTING.md

@@ -10,7 +10,7 @@ HVAC uses poetry to manage dependencies, the virtual environment, and versioning
 git clone https://github.com/hvac/hvac.git
 cd hvac
 
-poetry install --with dev
+poetry install --with dev,docs
 
 # Run the following command on Linux
 source $(poetry env info --path)/bin/activate
@@ -55,12 +55,18 @@ Should new dependencies need to be added, they can be simply added with Poetry.
 poetry add {package_name}
 ```
 
-If the dependency is only needed for development, add it to the `dev` group like so:
+If the dependency is only needed for development (including doctests), add it to the `dev` group like so:
 
 ```
 poetry add --group dev {dev_package_name}
 ```
 
+If the dependency is only needed for building docs (without doctest), add it to the `docs` group:
+
+```
+poetry add --group docs {docs_package_name}
+```
+
 ### Adding New Documentation Files
 
 When adding documentation for an entirely new feature / class, it often makes sense to place the documentation in a new `.rst` file. After drafting the new file, be sure to add the file as an entry to at least one table of contents directive (e.g., `toctree`) to ensure it gets rendered and published on https://hvac.readthedocs.io/. As an example, the process for adding a new documentation file for a secrets engine related to Active Directory could involve:
@@ -71,6 +77,12 @@ When adding documentation for an entirely new feature / class, it often makes se
 
 ### Testing Docs
 
+Ensure that both the `dev` and `docs` dependency groups are installed.
+
+```
+poetry install --with dev,docs
+```
+
 ```
 # Run the following command on Linux
 source $(poetry env info --path)/bin/activate

docs/conf.py

@@ -48,7 +48,7 @@
 # The master toctree document.
 master_doc = "index"
 
-language = None
+language = "en"
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 pygments_style = "sphinx"
 
@@ -87,7 +87,7 @@
 import os
 from pprint import pprint, pformat
 
-import mock
+import unittest.mock
 
 import hvac
 from tests import utils as test_utils

docs/ext/hvac_doctest.py

@@ -25,7 +25,7 @@
 import sphinx
 from sphinx.builders import Builder
 from sphinx.locale import __
-from sphinx.util import force_decode, logging
+from sphinx.util import logging
 from sphinx.util.console import bold  # type: ignore
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.nodes import set_source_info
@@ -368,8 +368,6 @@ def _warn_out(self, text):
             logger.warning(text)
         else:
             logger.info(text, nonl=True)
-        if isinstance(text, bytes):
-            text = force_decode(text, None)
         self.outfile.write(text)
 
     def get_target_uri(self, docname, typ=None):

pyproject.toml

@@ -53,7 +53,6 @@ Flask-SQLAlchemy = "^3.0.5"
 flake8 = "^5.0.0"
 coverage = "^6.3"
 ipaddress = "^1.0.23"
-mock = "^4.0.3"
 nose = "^1.3.7"
 parameterized = "^0.8.1"
 pyhcl = "^0.4.4"
@@ -62,20 +61,28 @@ pytest-cov = "^3.0.0"
 python-ldap-test = "^0.3.1"
 requests-mock = "^1.9.3"
 semantic-version = "^2.10.0"
-autodocsumm = "0.1.13"
-m2r2 = "0.2.5"
-Sphinx = "3.1.2"
-sphinx-rtd-theme = "0.5.0"
-mistune = "0.8.4"
-docutils = "<0.18"
 packaging = "<24"
-jinja2 = "<3.1.0"
 greenlet = "^3.0.0"
 jwcrypto = "^1.5.0"
 typos = "^1.16.11"
 pytest-mock = "^3.11.1"
 pytest-xdist = "^3.3.1"
 
+[tool.poetry.group.docs]
+optional = true
+
+# this group is for building docs
+# when running doctests, the dev group is needed too
+[tool.poetry.group.docs.dependencies]
+m2r2 = "^0.3.3"
+Sphinx = "^7"
+sphinx-rtd-theme = "^2"
+autodocsumm = "^0.2"
+docutils = "^0.20"
+jinja2 = "<3.1.0"
+setuptools = "^69"
+
+
 [tool.pytest.ini_options]
 addopts = "-n auto --dist worksteal"
 

tests/unit_tests/v1/test_system_backend_methods.py

@@ -1,7 +1,7 @@
 import pytest
 
 from pytest_mock import MockFixture
-from mock import MagicMock
+from unittest.mock import MagicMock
 from unittest import TestCase
 import requests_mock
 from parameterized import parameterized

tests/utils/__init__.py

@@ -8,7 +8,7 @@
 import socket
 import subprocess
 import typing as t
-from distutils.spawn import find_executable
+from shutil import which
 from unittest import SkipTest, mock
 
 from hvac import Client
@@ -23,7 +23,7 @@
 def get_vault_version_string():
     if "cache" in get_vault_version_string.__dict__:
         return get_vault_version_string.cache
-    if not find_executable("vault"):
+    if not which("vault"):
         raise SkipTest("Vault executable not found")
     command = ["vault", "-version"]
     process = subprocess.Popen(**get_popen_kwargs(args=command, stdout=subprocess.PIPE))