Wire Sphinx builds into the RTD config via tox

Resolves #917 Adjust test paths to new doc location.
pytest-dev · Aug 20, 2024 · 1bfc181 · 1bfc181
1 parent f03cf13
commit 1bfc181
Show file tree

Hide file tree

Showing 46 changed files with 62 additions and 73 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -1,19 +1,29 @@
 ---
-# Read the Docs configuration file for Sphinx projects
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
 version: 2
+
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: '3.12'
-
-sphinx:
-  configuration: docs/source/conf.py
-  fail_on_warning: true
-
-python:
-  install:
-  - requirements: dependencies/default/constraints.txt
-  - requirements: dependencies/docs/constraints.txt
-  - path: .
+    python: >-
+      3.12
+  commands:
+  - >-
+    PYTHONWARNINGS=error
+    python3 -Im venv "${READTHEDOCS_VIRTUALENV_PATH}"
+  - >-
+    PYTHONWARNINGS=error
+    "${READTHEDOCS_VIRTUALENV_PATH}"/bin/python -Im
+    pip install tox
+  - >-
+    PYTHONWARNINGS=error
+    "${READTHEDOCS_VIRTUALENV_PATH}"/bin/python -Im
+    tox -e docs --notest -vvvvv
+  - >-
+    PYTHONWARNINGS=error
+    "${READTHEDOCS_VIRTUALENV_PATH}"/bin/python -Im
+    tox -e docs --skip-pkg-install -q
+    --
+    "${READTHEDOCS_OUTPUT}"/html
+    -b html
+    -D language=en
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/source/concepts.rst → docs/concepts.rst b/docs/source/concepts.rst → docs/concepts.rst
diff --git a/...source/concepts_function_scope_example.py → docs/concepts_function_scope_example.py b/...source/concepts_function_scope_example.py → docs/concepts_function_scope_example.py
diff --git a/docs/source/concepts_module_scope_example.py → docs/concepts_module_scope_example.py b/docs/source/concepts_module_scope_example.py → docs/concepts_module_scope_example.py
diff --git a/docs/source/conf.py → docs/conf.py b/docs/source/conf.py → docs/conf.py
diff --git a/...to-guides/change_default_fixture_loop.rst → ...to-guides/change_default_fixture_loop.rst b/...to-guides/change_default_fixture_loop.rst → ...to-guides/change_default_fixture_loop.rst
diff --git a/...rce/how-to-guides/change_fixture_loop.rst → docs/how-to-guides/change_fixture_loop.rst b/...rce/how-to-guides/change_fixture_loop.rst → docs/how-to-guides/change_fixture_loop.rst
diff --git a/...-to-guides/change_fixture_loop_example.py → ...-to-guides/change_fixture_loop_example.py b/...-to-guides/change_fixture_loop_example.py → ...-to-guides/change_fixture_loop_example.py
diff --git a/...ow-to-guides/class_scoped_loop_example.py → ...ow-to-guides/class_scoped_loop_example.py b/...ow-to-guides/class_scoped_loop_example.py → ...ow-to-guides/class_scoped_loop_example.py
diff --git a/docs/source/how-to-guides/index.rst → docs/how-to-guides/index.rst b/docs/source/how-to-guides/index.rst → docs/how-to-guides/index.rst
diff --git a/...w-to-guides/module_scoped_loop_example.py → ...w-to-guides/module_scoped_loop_example.py b/...w-to-guides/module_scoped_loop_example.py → ...w-to-guides/module_scoped_loop_example.py
diff --git a/docs/source/how-to-guides/multiple_loops.rst → docs/how-to-guides/multiple_loops.rst b/docs/source/how-to-guides/multiple_loops.rst → docs/how-to-guides/multiple_loops.rst
diff --git a/...e/how-to-guides/multiple_loops_example.py → docs/how-to-guides/multiple_loops_example.py b/...e/how-to-guides/multiple_loops_example.py → docs/how-to-guides/multiple_loops_example.py
diff --git a/...-to-guides/package_scoped_loop_example.py → ...-to-guides/package_scoped_loop_example.py b/...-to-guides/package_scoped_loop_example.py → ...-to-guides/package_scoped_loop_example.py
diff --git a/...o-guides/run_class_tests_in_same_loop.rst → ...o-guides/run_class_tests_in_same_loop.rst b/...o-guides/run_class_tests_in_same_loop.rst → ...o-guides/run_class_tests_in_same_loop.rst
diff --git a/...-guides/run_module_tests_in_same_loop.rst → ...-guides/run_module_tests_in_same_loop.rst b/...-guides/run_module_tests_in_same_loop.rst → ...-guides/run_module_tests_in_same_loop.rst
diff --git a/...guides/run_package_tests_in_same_loop.rst → ...guides/run_package_tests_in_same_loop.rst b/...guides/run_package_tests_in_same_loop.rst → ...guides/run_package_tests_in_same_loop.rst
diff --git a/...guides/run_session_tests_in_same_loop.rst → ...guides/run_session_tests_in_same_loop.rst b/...guides/run_session_tests_in_same_loop.rst → ...guides/run_session_tests_in_same_loop.rst
diff --git a/...-to-guides/session_scoped_loop_example.py → ...-to-guides/session_scoped_loop_example.py b/...-to-guides/session_scoped_loop_example.py → ...-to-guides/session_scoped_loop_example.py
diff --git a/...urce/how-to-guides/test_item_is_async.rst → docs/how-to-guides/test_item_is_async.rst b/...urce/how-to-guides/test_item_is_async.rst → docs/how-to-guides/test_item_is_async.rst
diff --git a/...w-to-guides/test_item_is_async_example.py → ...w-to-guides/test_item_is_async_example.py b/...w-to-guides/test_item_is_async_example.py → ...w-to-guides/test_item_is_async_example.py
diff --git a/...uides/test_session_scoped_loop_example.py → ...uides/test_session_scoped_loop_example.py b/...uides/test_session_scoped_loop_example.py → ...uides/test_session_scoped_loop_example.py
diff --git a/docs/source/how-to-guides/uvloop.rst → docs/how-to-guides/uvloop.rst b/docs/source/how-to-guides/uvloop.rst → docs/how-to-guides/uvloop.rst
diff --git a/docs/source/index.rst → docs/index.rst b/docs/source/index.rst → docs/index.rst
diff --git a/docs/make.bat b/docs/make.bat
diff --git a/docs/source/reference/changelog.rst → docs/reference/changelog.rst b/docs/source/reference/changelog.rst → docs/reference/changelog.rst
diff --git a/docs/source/reference/configuration.rst → docs/reference/configuration.rst b/docs/source/reference/configuration.rst → docs/reference/configuration.rst
diff --git a/docs/source/reference/decorators/index.rst → docs/reference/decorators/index.rst b/docs/source/reference/decorators/index.rst → docs/reference/decorators/index.rst
diff --git a/...orators/pytest_asyncio_fixture_example.py → ...orators/pytest_asyncio_fixture_example.py b/...orators/pytest_asyncio_fixture_example.py → ...orators/pytest_asyncio_fixture_example.py
diff --git a/.../reference/fixtures/event_loop_example.py → .../reference/fixtures/event_loop_example.py b/.../reference/fixtures/event_loop_example.py → .../reference/fixtures/event_loop_example.py
diff --git a/...nce/fixtures/event_loop_policy_example.py → ...nce/fixtures/event_loop_policy_example.py b/...nce/fixtures/event_loop_policy_example.py → ...nce/fixtures/event_loop_policy_example.py
diff --git a/...event_loop_policy_parametrized_example.py → ...event_loop_policy_parametrized_example.py b/...event_loop_policy_parametrized_example.py → ...event_loop_policy_parametrized_example.py
diff --git a/docs/source/reference/fixtures/index.rst → docs/reference/fixtures/index.rst b/docs/source/reference/fixtures/index.rst → docs/reference/fixtures/index.rst
diff --git a/docs/source/reference/functions.rst → docs/reference/functions.rst b/docs/source/reference/functions.rst → docs/reference/functions.rst
diff --git a/docs/source/reference/index.rst → docs/reference/index.rst b/docs/source/reference/index.rst → docs/reference/index.rst
diff --git a/...op_custom_policies_strict_mode_example.py → ...op_custom_policies_strict_mode_example.py b/...op_custom_policies_strict_mode_example.py → ...op_custom_policies_strict_mode_example.py
diff --git a/.../class_scoped_loop_strict_mode_example.py → .../class_scoped_loop_strict_mode_example.py b/.../class_scoped_loop_strict_mode_example.py → .../class_scoped_loop_strict_mode_example.py
diff --git a/..._loop_with_fixture_strict_mode_example.py → ..._loop_with_fixture_strict_mode_example.py b/..._loop_with_fixture_strict_mode_example.py → ..._loop_with_fixture_strict_mode_example.py
diff --git a/...ed_loop_pytestmark_strict_mode_example.py → ...ed_loop_pytestmark_strict_mode_example.py b/...ed_loop_pytestmark_strict_mode_example.py → ...ed_loop_pytestmark_strict_mode_example.py
diff --git a/...nction_scoped_loop_strict_mode_example.py → ...nction_scoped_loop_strict_mode_example.py b/...nction_scoped_loop_strict_mode_example.py → ...nction_scoped_loop_strict_mode_example.py
diff --git a/docs/source/reference/markers/index.rst → docs/reference/markers/index.rst b/docs/source/reference/markers/index.rst → docs/reference/markers/index.rst
diff --git a/...module_scoped_loop_strict_mode_example.py → ...module_scoped_loop_strict_mode_example.py b/...module_scoped_loop_strict_mode_example.py → ...module_scoped_loop_strict_mode_example.py
diff --git a/docs/source/support.rst → docs/support.rst b/docs/source/support.rst → docs/support.rst
diff --git a/setup.cfg b/setup.cfg
@@ -65,7 +65,7 @@ show_missing = true
 [tool:pytest]
 python_files = test_*.py *_example.py
 addopts = -rsx --tb=short
-testpaths = docs/source tests
+testpaths = docs tests
 asyncio_mode = auto
 junit_family=xunit2
 filterwarnings =

diff --git a/tox.ini b/tox.ini
@@ -26,14 +26,48 @@ allowlist_externals =
     make
 
 [testenv:docs]
+allowlist_externals =
+    git
 extras = docs
 deps =
      --requirement dependencies/docs/requirements.txt
      --constraint dependencies/docs/constraints.txt
 change_dir = docs
-commands = make html
-allowlist_externals =
-    make
+description = Build The Docs with {basepython}
+commands =
+    # Retrieve possibly missing commits:
+    -git fetch --unshallow
+    -git fetch --tags
+
+    # Build the html docs with Sphinx:
+    {envpython} -Im sphinx \
+      -j auto \
+      {tty:--color} \
+      -a \
+      -T \
+      -n \
+      -W --keep-going \
+      -d "{temp_dir}{/}.doctrees" \
+      . \
+      {posargs:"{envdir}{/}docs_out" -b html}
+
+    # Print out the output docs dir and a way to serve html:
+    -{envpython} -c\
+    'import pathlib;\
+    docs_dir = pathlib.Path(r"{envdir}") / "docs_out";\
+    index_file = docs_dir / "index.html";\
+    print("\n" + "=" * 120 +\
+    f"\n\nOpen the documentation with:\n\n\
+    \t$ python3 -Im webbrowser \N\{QUOTATION MARK\}file://\{index_file\}\N\{QUOTATION MARK\}\n\n\
+    To serve docs, use\n\n\
+    \t$ python3 -Im http.server --directory \
+    \N\{QUOTATION MARK\}\{docs_dir\}\N\{QUOTATION MARK\} 0\n\n" +\
+    "=" * 120)'
+changedir = {toxinidir}{/}docs
+isolated_build = true
+passenv =
+    SSH_AUTH_SOCK
+skip_install = false
 
 [gh-actions]
 python =