Switch from doctest to Sybil

Author: adamtheturtle

.github/workflows/ci.yml

@@ -50,7 +50,9 @@ jobs:
 
       - name: "Run tests"
         run: |
-          pytest -s -vvv --cov-fail-under 100 --cov=src/ --cov=tests tests/ --cov-report=xml
+          # We run tests against "." and not the tests directory as we test the README
+          # and documentation.
+          pytest -s -vvv --cov-fail-under 100 --cov=src/ --cov=tests . --cov-report=xml
 
       - name: "Upload coverage to Codecov"
         uses: "codecov/codecov-action@v3"

Makefile

@@ -10,7 +10,6 @@ lint: \
     black \
     check-manifest \
     doc8 \
-    doctest \
     linkcheck \
     mypy \
     ruff \

README.md

@@ -0,0 +1,102 @@
+|Build Status| |codecov| |PyPI| |Documentation Status|
+
+vws-python
+==========
+
+Python library for the Vuforia Web Services (VWS) API and the Vuforia
+Web Query API.
+
+Installation
+------------
+
+.. code:: sh
+
+   pip install vws-python
+
+This is tested on Python 3.11+. Get in touch with
+``adamdangoor@gmail.com`` if you would like to use this with another
+language.
+
+Getting Started
+---------------
+
+.. invisible-code-block: python
+
+   import pathlib
+   import shutil
+
+   import vws_test_fixtures
+   from mock_vws import MockVWS
+   from mock_vws.database import VuforiaDatabase
+
+   mock = MockVWS(real_http=False)
+   database = VuforiaDatabase(
+       server_access_key='[server-access-key]',
+       server_secret_key='[server-secret-key]',
+       client_access_key='[client-access-key]',
+       client_secret_key='[client-secret-key]',
+   )
+   mock.add_database(database=database)
+   mock.__enter__()
+
+   # We rely on implementation details of the fixtures package.
+   image = pathlib.Path(vws_test_fixtures.__path__[0]) / 'high_quality_image.jpg'
+   assert image.exists(), image.resolve()
+   new_image = pathlib.Path('high_quality_image.jpg')
+   shutil.copy(image, new_image)
+
+
+.. code-block:: python
+
+   import pathlib
+
+   from vws import VWS, CloudRecoService
+
+   server_access_key = '[server-access-key]'
+   server_secret_key = '[server-secret-key]'
+   client_access_key = '[client-access-key]'
+   client_secret_key = '[client-secret-key]'
+
+   vws_client = VWS(
+       server_access_key=server_access_key,
+       server_secret_key=server_secret_key,
+   )
+   cloud_reco_client = CloudRecoService(
+       client_access_key=client_access_key,
+       client_secret_key=client_secret_key,
+   )
+   name = 'my_image_name'
+
+   image = pathlib.Path('high_quality_image.jpg')
+   with image.open(mode='rb') as my_image_file:
+       target_id = vws_client.add_target(
+           name=name,
+           width=1,
+           image=my_image_file,
+           active_flag=True,
+           application_metadata=None,
+       )
+       vws_client.wait_for_target_processed(target_id=target_id)
+       matching_targets = cloud_reco_client.query(image=my_image_file)
+
+   assert matching_targets[0].target_id == target_id
+
+.. invisible-code-block: python
+   new_image = pathlib.Path('high_quality_image.jpg')
+   new_image.unlink()
+   mock.__exit__()
+
+Full Documentation
+------------------
+
+See the `full
+documentation <https://vws-python.readthedocs.io/en/latest>`__.
+
+.. |Build Status| image:: https://github.com/VWS-Python/vws-python/workflows/CI/badge.svg
+   :target: https://github.com/VWS-Python/vws-python/actions
+.. |codecov| image:: https://codecov.io/gh/VWS-Python/vws-python/branch/master/graph/badge.svg
+   :target: https://codecov.io/gh/VWS-Python/vws-python
+.. |PyPI| image:: https://badge.fury.io/py/VWS-Python.svg
+   :target: https://badge.fury.io/py/VWS-Python
+.. |Documentation Status| image:: https://readthedocs.org/projects/vws-python/badge/?version=latest
+   :target: https://vws-python.readthedocs.io/en/latest/?badge=latest

README.rst

@@ -0,0 +1,15 @@
+from doctest import ELLIPSIS
+
+from sybil import Sybil
+from sybil.parsers.rest import (
+    DocTestParser,
+    PythonCodeBlockParser,
+)
+
+pytest_collect_file = Sybil(
+    parsers=[
+        DocTestParser(optionflags=ELLIPSIS),
+        PythonCodeBlockParser(),
+    ],
+    patterns=["*.rst", "*.py"],
+).pytest()

conftest.py

@@ -13,7 +13,6 @@
 
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx_autodoc_typehints",

docs/source/conf.py

@@ -16,7 +16,7 @@ Usage
 
 See the :doc:`api-reference` for full usage details.
 
-.. testsetup:: simple
+.. invisible-code-block: python
 
    import pathlib
    import shutil
@@ -41,7 +41,7 @@ See the :doc:`api-reference` for full usage details.
    new_image = pathlib.Path('high_quality_image.jpg')
    shutil.copy(image, new_image)
 
-.. testcode:: simple
+.. code-block:: python
 
    import pathlib
 
@@ -76,7 +76,7 @@ See the :doc:`api-reference` for full usage details.
 
    assert matching_targets[0].target_id == target_id
 
-.. testcleanup:: simple
+.. invisible-code-block: python
 
    new_image = pathlib.Path('high_quality_image.jpg')
    new_image.unlink()
@@ -91,7 +91,14 @@ To write unit tests for code which uses this library, without using your Vuforia
 
    pip3 install vws-python-mock
 
-.. testsetup:: testing
+.. invisible-code-block: python
+
+   # Reset test
+   for i in list(globals().keys()):
+    if not i.startswith('_'):
+        exec('del ' + i)
+
+.. invisible-code-block: python
 
    import pathlib
    import shutil
@@ -104,7 +111,7 @@ To write unit tests for code which uses this library, without using your Vuforia
    new_image = pathlib.Path('high_quality_image.jpg')
    shutil.copy(image, new_image)
 
-.. testcode:: testing
+.. code-block:: python
 
    import pathlib
 
@@ -135,7 +142,7 @@ To write unit tests for code which uses this library, without using your Vuforia
             active_flag=True,
          )
 
-.. testcleanup:: testing
+.. invisible-code-block: python
 
    new_image = pathlib.Path('high_quality_image.jpg')
    new_image.unlink()

docs/source/index.rst

@@ -40,7 +40,7 @@ pip-missing-reqs:
 
 .PHONY: pylint
 pylint:
-	pylint src/ tests/ docs/
+	pylint *.py src/ tests/ docs/
 
 .PHONY: pyroma
 pyroma:
@@ -56,9 +56,4 @@ linkcheck:
 
 .PHONY: spelling
 spelling:
-	$(MAKE) -C docs/ spelling SPHINXOPTS=$(SPHINXOPTS)
-
-.PHONY: doctest
-doctest:
-	$(MAKE) -C docs/ doctest SPHINXOPTS=$(SPHINXOPTS)
-	pytest --codeblocks README.md
+	$(MAKE) -C docs/ spelling SPHINXOPTS=$(SPHINXOPTS)

lint.mk

@@ -213,7 +213,7 @@ dynamic = ["version"]
 keywords = ["vuforia", "vws", "client"]
 license = { file = "LICENSE" }
 name = "vws-python"
-readme = { file = "README.md", content-type = "text/markdown"}
+readme = { file = "README.rst", content-type = "text/x-rst"}
 requires-python = ">=3.10"
 dependencies = [
     "VWS-Auth-Tools",
@@ -244,12 +244,12 @@ dev = [
     "pylint==2.17.0 ",
     "pyroma==4.2",
     "pytest-cov==4.0.0",
-    "pytest_codeblocks==0.16.1",
     "pytest==7.2.2 ",
     "ruff==0.0.256",
     "sphinx-autodoc-typehints==1.22",
     "sphinx-prompt==1.5.0",
     "sphinxcontrib-spelling==8.0.0",
+    "sybil==4.0.1",
     "types-freezegun==1.1.10",
     "types-requests==2.28.11.15",
     "vulture==2.7",