Add docrun pre-commit hooks

.pre-commit-config.yaml

@@ -1,3 +1,5 @@
+fail_fast: true
+
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
 
@@ -6,25 +8,32 @@ ci:
     # We therefore cannot use those dependencies in pre-commit CI.
     skip:
         - actionlint
-        - mypy
         - check-manifest
-        - pyright
-        - vulture
-        - pyroma
         - deptry
-        - pylint
-        - ruff-check
-        - ruff-format-diff
-        - ruff-check-fix
-        - ruff-format-fix
         - doc8
+        - docs
         - interrogate
+        - interrogate-docs
+        - linkcheck
+        - mypy
+        - mypy-docs
+        - pylint
         - pyproject-fmt-check
         - pyproject-fmt-fix
-        - linkcheck
-        - spelling
-        - docs
+        - pyright
+        - pyright-docs
         - pyright-verifytypes
+        - pyroma
+        - ruff-check
+        - ruff-check-docs
+        - ruff-check-fix
+        - ruff-check-fix-docs
+        - ruff-format-diff
+        - ruff-format-diff-docs
+        - ruff-format-fix
+        - ruff-format-fix-docs
+        - spelling
+        - vulture
 
 default_install_hook_types: [pre-commit, pre-push, commit-msg]
 repos:
@@ -66,6 +75,13 @@ repos:
         types_or: [python, toml]
         pass_filenames: false
 
+    -   id: mypy-docs
+        name: mypy-docs
+        stages: [push]
+        entry: doccmd --language=python --command="mypy"
+        language: system
+        types_or: [markdown, rst, python, toml]
+
     -   id: check-manifest
         name: check-manifest
         stages: [push]
@@ -81,6 +97,13 @@ repos:
         types_or: [python, toml]
         pass_filenames: false
 
+    -   id: pyright-docs
+        name: pyright-docs
+        stages: [push]
+        entry: doccmd --language=python --command="pyright"
+        language: system
+        types_or: [markdown, rst, python, toml]
+
     -   id: vulture
         name: vulture
         entry: python -m vulture --min-confidence 100 --exclude .eggs
@@ -107,30 +130,61 @@ repos:
         stages: [manual]
         pass_filenames: false
 
+    -   id: pylint-docs
+        name: pylint-docs
+        entry: doccmd --language=python --command="pylint" --lowercase-file-name
+        language: system
+        stages: [manual]
+        types_or: [markdown, rst, python, toml]
+
     -   id: ruff-check
         name: Ruff check
         entry: python -m ruff check
         language: system
         types_or: [python]
 
+    -   id: ruff-check-docs
+        name: Ruff check docs
+        entry: doccmd --language=python --command="ruff check"
+        language: system
+        types_or: [markdown, rst]
+
     -   id: ruff-format-diff
         name: Ruff format diff
         entry: python -m ruff format --diff
         language: system
         types_or: [python]
 
+    -   id: ruff-format-diff-docs
+        name: Ruff format diff docs
+        entry: doccmd --language=python --no-pad-file --command="ruff format --diff"
+        language: system
+        types_or: [markdown, rst]
+
     -   id: ruff-check-fix
         name: Ruff check fix
         entry: python -m ruff check --fix
         language: system
         types_or: [python]
 
+    -   id: ruff-check-fix-docs
+        name: Ruff check fix docs
+        entry: doccmd --language=python --command="ruff check --fix"
+        language: system
+        types_or: [markdown, rst]
+
     -   id: ruff-format-fix
         name: Ruff format
         entry: python -m ruff format
         language: system
         types_or: [python]
 
+    -   id: ruff-format-fix-docs
+        name: Ruff format docs
+        entry: doccmd --language=python --no-pad-file --command="ruff format"
+        language: system
+        types_or: [markdown, rst]
+
     -   id: doc8
         name: doc8
         entry: python -m doc8
@@ -143,6 +197,12 @@ repos:
         language: system
         types_or: [python]
 
+    -   id: interrogate-docs
+        name: interrogate docs
+        entry: doccmd --language=python --command="interrogate"
+        language: system
+        types_or: [markdown, rst]
+
     -   id: pyproject-fmt-check
         name: pyproject-fmt check
         entry: pyproject-fmt --check

README.rst

@@ -22,38 +22,57 @@ Getting Started
 
 .. code-block:: python
 
+   """Add a target to VWS and then query it."""
+
    import pathlib
+   import uuid
 
    from vws import VWS, CloudRecoService
+   from vws.reports import QueryResult
+
 
-   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,
+   def add_target() -> str:
+       """Add a target to VWS and return its ID."""
+       server_access_key = "[server-access-key]"
+       server_secret_key = "[server-secret-key]"
+       vws_client = VWS(
+           server_access_key=server_access_key,
+           server_secret_key=server_secret_key,
+       )
+       name = "my_image_name_" + uuid.uuid4().hex
+
+       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)
+
+       return target_id
+
+
+   def get_matching_targets() -> list[QueryResult]:
+       """Query VWS for matching targets."""
+       client_access_key = "[client-access-key]"
+       client_secret_key = "[client-secret-key]"
+
+       cloud_reco_client = CloudRecoService(
+           client_access_key=client_access_key,
+           client_secret_key=client_secret_key,
        )
-       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
+       image = pathlib.Path("high_quality_image.jpg")
+       with image.open(mode="rb") as my_image_file:
+           return cloud_reco_client.query(image=my_image_file)
+
+
+   TARGET_ID = add_target()
+   MATCHING_TARGETS = get_matching_targets()
+   assert MATCHING_TARGETS[0].target_id == TARGET_ID
 
 Full Documentation
 ------------------

docs/source/index.rst

@@ -18,40 +18,57 @@ See the :doc:`api-reference` for full usage details.
 
 .. code-block:: python
 
+   """Add a target to VWS and then query it."""
+
    import pathlib
+   import uuid
 
    from vws import VWS, CloudRecoService
+   from vws.reports import QueryResult
 
-   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,
-   )
-   import uuid
-   name = 'my_image_name' + uuid.uuid4().hex
-
-   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
-   a = 1
+
+   def add_target() -> str:
+       """Add a target to VWS and return its ID."""
+       server_access_key = "[server-access-key]"
+       server_secret_key = "[server-secret-key]"
+       vws_client = VWS(
+           server_access_key=server_access_key,
+           server_secret_key=server_secret_key,
+       )
+       name = "my_image_name_" + uuid.uuid4().hex
+
+       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)
+
+       return target_id
+
+
+   def get_matching_targets() -> list[QueryResult]:
+       """Query VWS for matching targets."""
+       client_access_key = "[client-access-key]"
+       client_secret_key = "[client-secret-key]"
+
+       cloud_reco_client = CloudRecoService(
+           client_access_key=client_access_key,
+           client_secret_key=client_secret_key,
+       )
+
+       image = pathlib.Path("high_quality_image.jpg")
+       with image.open(mode="rb") as my_image_file:
+           return cloud_reco_client.query(image=my_image_file)
+
+
+   TARGET_ID = add_target()
+   MATCHING_TARGETS = get_matching_targets()
+   assert MATCHING_TARGETS[0].target_id == TARGET_ID
 
 Testing
 -------
@@ -66,33 +83,47 @@ To write unit tests for code which uses this library, without using your Vuforia
 
 .. code-block:: python
 
-   import pathlib
+    """Add a target to VWS and then query it."""
 
-   from mock_vws.database import VuforiaDatabase
-   from mock_vws import MockVWS
-   from vws import CloudRecoService, VWS
+    import pathlib
+
+    from mock_vws import MockVWS
+    from mock_vws.database import VuforiaDatabase
+
+    from vws import VWS, CloudRecoService
+
+
+    def test_add_target() -> None:
+        """Test adding a target to VWS."""
+        with MockVWS() as mock:
+            database = VuforiaDatabase()
+            mock.add_database(database=database)
+            vws_client = VWS(
+                server_access_key=database.server_access_key,
+                server_secret_key=database.server_secret_key,
+            )
+            cloud_reco_client = CloudRecoService(
+                client_access_key=database.client_access_key,
+                client_secret_key=database.client_secret_key,
+            )
+
+            image = pathlib.Path("high_quality_image.jpg")
+            with image.open(mode="rb") as my_image_file:
+                target_id = vws_client.add_target(
+                    name="example_image_name",
+                    width=1,
+                    image=my_image_file,
+                    application_metadata=None,
+                    active_flag=True,
+                )
+
+                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
 
-   with MockVWS() as mock:
-       database = VuforiaDatabase()
-       mock.add_database(database=database)
-       vws_client = VWS(
-           server_access_key=database.server_access_key,
-           server_secret_key=database.server_secret_key,
-       )
-       cloud_reco_client = CloudRecoService(
-           client_access_key=database.client_access_key,
-           client_secret_key=database.client_secret_key,
-       )
 
-       image = pathlib.Path('high_quality_image.jpg')
-       with image.open(mode='rb') as my_image_file:
-         target_id = vws_client.add_target(
-            name="example_image_name",
-            width=1,
-            image=my_image_file,
-            application_metadata=None,
-            active_flag=True,
-         )
+    test_add_target()
 
 There are some differences between the mock and the real Vuforia.
 See https://vws-python-mock.readthedocs.io/en/latest/differences-to-vws.html for details.