Docs for .pyi (#165)

* mkdocstrings for .pyi file

* try updating mkdocstrings-python

* complete _rust_notify docs

* uprev test requirements.txt

docs/api/rust_backend.md

@@ -1,8 +1,10 @@
-The `_rust_notify.pyi` file defines the interface to rust:
+::: watchfiles._rust_notify.RustNotify
 
-```{.py title="_rust_notify.pyi" test="skip"}
-{! watchfiles/_rust_notify.pyi !}
-```
+::: watchfiles._rust_notify.WatchfilesRustInternalError
+
+::: watchfiles._rust_notify.__version__
+
+# Rust backend direct usage
 
 The rust backend can be accessed directly as follows:
 

docs/plugins.py

@@ -26,9 +26,15 @@ def test_examples():
         logger.info('pytest not installed, skipping examples tests')
     else:
         logger.info('running examples tests...')
-        return_code = pytest.main(['-q', '-p', 'no:sugar', 'tests/test_docs.py'])
-        if return_code != 0:
-            logger.warning('examples tests failed')
+        try:
+            pytest.main(['--version'])
+        except AttributeError:
+            # happens if pytest is not properly installed
+            logger.info('pytest not installed correctly, skipping examples tests')
+        else:
+            return_code = pytest.main(['-q', '-p', 'no:sugar', 'tests/test_docs.py'])
+            if return_code != 0:
+                logger.warning('examples tests failed')
 
 
 def on_files(files: Files, config: Config) -> Files:

docs/requirements.txt

@@ -1,6 +1,8 @@
 black==22.3.0
-mkdocs==1.2.3
-mkdocs-material==8.2.7
+griffe==0.20.0
+mkdocs==1.3.0
+mkdocs-material==8.3.7
 mkdocs-simple-hooks==0.1.5
-mkdocstrings[python]==0.18.1
+mkdocstrings[python]==0.19.0
+mkdocstrings-python==0.7.1
 mdx-include==1.4.1

tests/requirements.txt

@@ -1,6 +1,6 @@
-coverage==6.3.2
-dirty-equals==0.2
-pytest==7.1.1
+coverage==6.4.1
+dirty-equals==0.4
+pytest==7.1.2
 pytest-mock==3.7.0
 pytest-sugar==0.9.4
 pytest-timeout==2.1.0

watchfiles/_rust_notify.pyi

@@ -3,6 +3,7 @@ from typing import List, Literal, Optional, Protocol, Set, Tuple, Union
 __all__ = 'RustNotify', 'WatchfilesRustInternalError'
 
 __version__: str
+"""Gets the package version as defined in `Cargo.toml`, modified to match python's versioning semantics."""
 
 class AbstractEvent(Protocol):
     def is_set(self) -> bool: ...