add documentation about robot2python

README.md

@@ -81,6 +81,30 @@ def test_bar():
     ...
 ```
 
+## automatically convert `.robot` tests to `.py`
+
+pytest-robotframework comes with a script to automatically convert tests from robot to python:
+
+```
+robot2python ./foo.robot ./tests
+```
+
+this will convert the `foo.robot` file to an equivalent `test_foo.py` file and output it to the `tests` directory.
+
+### limitations
+
+note that the script is not perfect and you will probably have to make manual changes to tests converted with it.
+
+- because the script doesn't know what exactly what keywords are being imported from each library:
+
+  - outside of some special cased keywords in the robot `BuiltIn` library, keywords are currently not resolved, so robot `Library` imports are converted to star-imports (ie. `Library  library_name` -> `from library_name import *`).
+
+    star imports [should not be used](https://docs.astral.sh/ruff/rules/undefined-local-with-import-star/), so you should manually update them to import individual keywords explicitly.
+
+  - robot converters are not yet used, so all arguments to keywords are assumed to be strings in the converted python code.
+
+- some of the control flows possible in robot aren't able to be accurately converted to python (see [here](#continuable-failures-dont-work)). the script attempts to convert what it can but you will probably have to rewrite parts of your tests that use continuable failures
+
 ## setup/teardown and other hooks
 
 to define a function that runs for each test at setup or teardown, create a `conftest.py` with a `pytest_runtest_setup` and/or `pytest_runtest_teardown` function: